Google Ads Query Builder

The Google Ads Query Builder is an interactive tool designed to help you interactively construct and validate queries using the Google Ads Query Language (GAQL). Whether you're new to GAQL or an experienced user, the Query Builder can simplify the process of fetching the exact data you need from the Google Ads API.

Benefits

  • Ease of use: Simplifies the process of writing GAQL queries, without requiring familiarity with the specific syntax and available fields.
  • Discoverability: Helps explore and find available resources, fields, segments, and metrics within the Google Ads API data model.
  • Reduced errors: By providing a structured interface and drop-down menus of valid options, it helps prevent syntax errors and typos, ensuring the generated query is valid.
  • Faster query building: Speeds up the development process by automating the generation of query strings.
  • Validation: The tool is linked with the API Explorer and Query Validator, to check queries against API rules before execution.

How it works

The Google Ads Query Builder provides a user-friendly interface to visually assemble GAQL queries. Here's the basic workflow:

  1. Select a resource: You start by choosing the primary resource from the Reference tab for the version you want to query. This resource will be in the FROM clause. Resources represent entities within Google Ads, such as campaign, ad_group, or keyword_view. The builder lists all available resources.
  2. Choose fields: Once a resource is selected, the tool displays all the selectable fields, including attributes, segments, and metrics related to that resource and its attributed (implicitly joinable) resources. You can check boxes to include fields in your SELECT clause. As you make selections, the tool dynamically generates the corresponding GAQL query string, displays any errors, and filters out incompatible field combinations.
  3. Apply filters: You can add WHERE clause conditions to filter the results. The builder helps you choose fields, operators, and values, ensuring correct syntax.
  4. Order results: Specify sorting orders using the ORDER BY clause.
  5. Set limits: Add a LIMIT clause to control the number of results returned.
  6. Validate: The tool inherently guides you towards valid field combinations, but also links to the API Explorer so you can test your query against your account data. There's also a separate [Query Validator](link to page) where you can paste and check manually written GAQL queries.
  7. Export: Once you're satisfied with your query, copy and paste your tested, syntactically correct GAQL string into your GoogleAdsService.Search or SearchStream client requests.

The builder ensures that the selected fields, segments, and metrics are compatible and can be used together in a single query, referencing the underlying metadata of the Google Ads API.

Get started

There are two ways to get to the Query Builder. One option is to go through a specific page in the reporting reference docs, and the other is to explore from the Query Builder overview page.

From the reporting reference docs

  1. Start with the reporting reference docs, and choose a specific resource to start with in the list of all resources. Alternatively, navigate directly to the resource from the left navigation pane.
  2. Click Help me build a query, which brings you to the Query Builder for that specific resource.

From the Query Builder overview page

Go to the Query Builder section of the reporting reference docs and select the resource you want to explore.

Integration with other tools

The Query Builder is integrated with other tools in the Google Ads API Developer Toolkit. You can take a query built in the Query Builder and test it in the API Explorer or validate it with the Query Validator.

API Explorer

Once you have built your query, click Try in API Explorer to open your query in the API Explorer. Your query will automatically be populated in the request body, and you can then test your query by running it against your account data. See API Explorer for more information on that tool.

Query Validator

When you click Enter or edit a query, the Query Validator opens. Use the Query Validator to validate the syntax of your query. Any query built entirely through the Query Builder will already have the correct syntax, but if you're familiar with the resource you're querying, the Query Validator will provide a fast way to input a query and check its validity. See Query Validator for more information on that tool.