Pass context to queries with prompts

When you need to improve the accuracy of your queries, query contexts allow you to provide AgentQL more precise instructions to improve your results.

Overview

This section shows you how to use semantic and structural contexts to focus your query. Semantic contexts leverage natural language to enhance your queries while structural contexts rely on data structures to enhance queries.

Semantic contexts

Semantic contexts allow you to use natural language to enhance your queries by wrapping them in parentheses () and appending them to the property.

Here's an e-commerce example of a query enhanced with semantic contexts to shape the data with specific parameters:

{
    products(Exclude sponsored results or ads)[] {
        name
        description(Summarize within 150 words)
        price(Display in local currency with two decimal places)
    }
}
tip

The more descriptive you are with describing the context, the better AgentQL can follow your instructions.

Adding conditions

When you need AgentQL to filter out data based on certain conditionals, you can provide semantic context to the desired property.

In the e-commerce example, the query uses conditions on products to exclude all sponsored results and ads.

{
    products(Exclude sponsored results or ads)[] {
        name
        description
        price
    }
}
info

Specifying conditions in your queries may produce inconsistent results because it relies on AI to understand your intent. For more precise and advanced filtering, extract the data first and then filter it using conventional programming methods.

Requesting summaries

AgentQL is also able to summarize text fields with specific parameters such as word length to transform long strings of text into more concise summaries.

In the e-commerce products example, the description property utilizes the summaries context to ensure that all returned conditions stay within the 150 words parameter.

{
    products[] {
        name
        description(Summarize within 150 words)
        price
    }
}

Formatting data

When you need to format data in a specific format, AgentQL also allows you to request specific formats with natural language.

In the e-commerce example, AgentQL formats all pricing according to the local currency within two decimal places. For example: $29.99, €15.50, etc.

{
    products[] {
        name
        description
        price(Display in local currency with two decimal places)
    }
}
info

Formatting data with AgentQL queries may produce inconsistent results because it relies on AI to understand your intent. For precise formatting, extract the data first and then format it using conventional programming methods.

Specify HTML properties

You can also add context to select specific HTML properties. Ocassionally AgentQL may return the wrong element. In this case, you can add context to ensure the specific html properties you want. Here are some examples:

{
    products(must be a span tag)[]
}
{
    products(must be a span tag with class="product-name")[]
}

Structual contexts

Structural contexts utilize the query's data structure to provide context for the desired data. For example, you can structure the query to tell AgentQL the approximate location of the data you are looking for and its relation to other data on the page.

{
    footer {
        about_us
        contact_us
        social_media_links[]
    }
}

In this example, the structure of the query tells the system to prioritize about_us, contact_us, and social_media_links in the footer of the page over similar elements on the page.

tip

Semantic context are generally recommended over structural contexts because it's easier to understand and more explicit.

The structual context example can also be re-written with semantic context as follows:

{
  about_us(located in the footer)
  contact_us(located in the footer)
  social_media_links(footer links)[]
}

Conclusion

You can refine the elements and data AgentQL queries return by incorporating contextual information into your queries. This approach improves accuracy and provides flexibility in handling complex web structures and specific data requirements. As you become more familiar with contextual queries, you'll find them invaluable for efficiently tackling a wide range of web scraping challenges.

Related Content