AQLResponseProxy

The AQLResponseProxy class is returned by the AgentQL's Page's queryElements() method. It's not the actual data but a metadata structure that allows intuitive access to web elements using dot notation. You can convert this class into raw data as a structured dictionary using its toData() method.

To access desired web elements, users can directly use the names defined in queries as attributes of the response object. It returns desired elements as Playwright Locator, and users can interact with these elements, such as click or type, through the Playwright Locator API.

The following example queries for web elements through the queryElements() method, interacts with these elements through AQLResponseProxy objects, and converts AQLResponseProxy objects into raw data.

Example Usage

const { configure, wrap } = require('agentql');
const { chromium } = require('playwright');

const QUERY = `
{
    search_box
    header {
        search_btn
    }
}
`;

(async () => {
  // Configure the API key
  configure({ apiKey: process.env.AGENTQL_API_KEY });

  const browser = await chromium.launch({ headless: false });
  const page = await wrap(await browser.newPage());
  await page.goto('https://duckduckgo.com');

  // Get AQLResponseProxy, which contains desired web elements
  const aqlResponse = await page.queryElements(QUERY); 

  // Access the elements with dot notation and interact with them as Playwright Locator objects
  await aqlResponse.search_box.type('AgentQL'); 

  // To access a nested element in query, simply chain attributes together with dot notation
  await aqlResponse.header.search_btn.click(); 

  // Convert response into raw data as structured map with toData() method
  const rawDataInDict = await aqlResponse.toData(); 
  console.log(rawDataInDict);

  // Used only for demo purposes. It allows you to see the effect of the script.
  await page.waitForTimeout(10000);

  await browser.close();
})();

Methods

toData

Converts the response data into a structured map based on the query tree.

Usage

const aqlResponse = await page.queryElements(QUERY);
const data = await aqlResponse.toData();

Returns

{
  "query_field": "text content of the corresponding web element"
}

getAttribute

This method is used to access attributes of the response object. If called on an innermost node of the query, it returns the desired web element as a Playwright Locator. Please check the Playwright Locator API for available methods.

If called on a container node of the query, it returns another AQLResponseProxy object.

Usage

const QUERY = `
{
    search_btn
    search_results[]
}
`;

const aqlResponse = await page.queryElements(QUERY);

// This invokes Playwright Locator object's click() method
await aqlResponse.search_btn.click();

// This iterates through search results with AQLResponseProxy
for (const searchResult of aqlResponse.search_results) {
  console.log(searchResult);
}

Arguments

  • name String: The name of the attribute to access.

Returns

The corresponding AQLResponseProxy or Playwright Locator object.

getItem

Allows indexing into the response data if it's an array.

Usage

const QUERY = `
{
    search_results[]
}
`;

const aqlResponse = await page.queryElements(QUERY);

// Get the second result in the list
const secondResult = aqlResponse.search_results[1];

Returns

The corresponding AQLResponseProxy or Playwright Locator object at the specified index.

getLength

Returns the number of items in the response data if it's an array.

Usage

const QUERY = `
{
    search_results[]
}
`;

const aqlResponse = await page.queryElements(QUERY);

// Get the number of search results
const resultCount = aqlResponse.search_results.length;

Returns

The number of items in the array.