> [!TIP]
> **Tip:** Use the [Interactive Query Builder](https://developers.google.com/google-ads/api/fields/v26/overview_query_builder) to build and validate your GAQL queries.

## Key terminology

Resource
:   An entity in Google Ads, such as `campaign` or `ad_group`.

Segment
:   A dimension used to group data, such as `segments.date` or `segments.device`.
    When segments are included in the `SELECT` clause with metrics, metrics are
    split by segment.

Metric
:   A measurement of performance, such as `metrics.impressions` or
    `metrics.clicks`.

Attributed Resource
:   A resource that is implicitly joined to the main resource in the `FROM`
    clause, allowing you to select its attributes along with main resource
    attributes.

## Query for resource or metadata information

The Google Ads Query Language can query the Google Ads API for the following types of information:

- Resources and their related attributes, segments, and metrics using
  [`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) *Search* or *SearchStream* :
  The result from a `GoogleAdsService` query is a list of
  [`GoogleAdsRow`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsRow) instances, with each
  `GoogleAdsRow` representing a resource.

  If any attributes or metrics are requested, then the row also includes those
  fields. If any segments are requested, then the response also shows an
  additional row for each segment-resource tuple.
- Metadata about available fields and resources in
  [`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsFieldService):
  This service provides a catalog of queryable fields with specifics about their
  compatibility and type.

  The result from a `GoogleAdsFieldService` query is a list of
  [`GoogleAdsField`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsField) instances, with each
  `GoogleAdsField` containing details about the requested field.

For more details on query structure, see
[Query structure](https://developers.google.com/google-ads/api/docs/query/structure) and
[Google Ads Query Language grammar](https://developers.google.com/google-ads/api/docs/query/grammar).

### Query for resource attributes

Here is an example of a basic query for attributes of the campaign resource that
illustrates how to return the campaign ID, name, and status:

    SELECT
      campaign.id,
      campaign.name,
      campaign.status
    FROM campaign
    ORDER BY campaign.id

This query orders by campaign ID. Each resulting `GoogleAdsRow` represents a
`campaign` object populated with the selected fields, including the campaign's
`resource_name`.

To find out what other fields are available for campaign queries, consult the
[`Campaign` reference documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/Campaign).

### Query for metrics

Alongside selected attributes for a given resource, you can also query for
related metrics:

    SELECT
      campaign.id,
      campaign.name,
      campaign.status,
      metrics.impressions
    FROM campaign
    WHERE campaign.status = 'PAUSED'
      AND metrics.impressions > 1000
    ORDER BY campaign.id

This query filters for only the campaigns that have a status of `PAUSED` and
have had greater than 1000 impressions, while ordering by campaign ID. Each
resulting `GoogleAdsRow` would have a `metrics` field populated with the
selected metrics.

For a list of queryable metrics, consult the
[`Metrics` documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/Metrics).

### Query for segments

Alongside selected attributes for a given resource, you can also query for
related segments:

    SELECT
      campaign.id,
      campaign.name,
      campaign.status,
      metrics.impressions,
      segments.date
    FROM campaign
    WHERE campaign.status = 'PAUSED'
      AND metrics.impressions > 1000
      AND segments.date DURING LAST_30_DAYS
    ORDER BY campaign.id

Similar to querying for metrics, this query filters for only the campaigns that
have a status of `PAUSED` and have had greater than 1000 impressions. However,
this query segments the data by date. This leads to each resulting
`GoogleAdsRow` representing a tuple of a campaign and the date segment.
Segmenting splits the selected metrics, grouping by each segment in the `SELECT`
clause.

For a list of queryable segments, consult the
[`Segments` documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/Segments).

### Query for attributes of a related resource

In a query for a given resource, you may be able to join against other related
resources if available. These related resources are known as "attributed
resources". You can join against attributed resources implicitly by selecting an
attribute in your query.

    SELECT
      campaign.id,
      campaign.name,
      campaign.status,
      bidding_strategy.name
    FROM campaign
    ORDER BY campaign.id

This query not only selects campaign attributes, but also pulls in related
attributes from each campaign selected. Each resulting `GoogleAdsRow` represents
a `campaign` object populated with the selected campaign attributes, as well as
the selected bidding strategy attribute `bidding_strategy.name`.

To find out what attributed resources are available for campaign queries,
consult the [`Campaign` reference documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/Campaign).

## Best practices

- Select only the fields you need to avoid long response times and timeouts.
- Use `LIMIT` during development and testing to avoid processing large result sets.
- Apply filters in the `WHERE` clause to minimize data transfer and response size.
- Use [`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsFieldService) to check field compatibility and data types before constructing complex queries.
- Be mindful that some fields, especially those involving large amounts of data or complex calculations, can increase query cost.

## Mutate based on query results

When querying for a given resource, you can immediately take those returned
results as objects, modify them, and send them back to the mutate method in that
resource's service. Here is a sample workflow:

1. Execute a query for all `PAUSED` campaigns that have impressions greater than 1000.
2. Get the `Campaign` object from the `campaign` field of each `GoogleAdsRow` in the response.
3. Change the status of each campaign from `PAUSED` to `ENABLED`.
4. Call [`CampaignService.MutateCampaigns`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignService) with the modified campaigns and a corresponding `FieldMask` to update them.

> [!NOTE]
> **Note:** When updating resources retrieved from a query, specify a `FieldMask` (or use your client library's built-in field mask utility) so that only the modified fields are updated, avoiding `READ_ONLY_FIELD` or `IMMUTABLE_FIELD` errors, or unintentionally overwriting other attributes.

## Field metadata

Queries sent to `GoogleAdsFieldService` are meant for retrieving field metadata.
This information can be used to understand how the fields can be used together
in a query. Since data is available from the API and it provides the necessary
metadata needed to validate or build a query, this allows for developers to do
so programmatically. Here's a typical query for metadata:

    SELECT
      name,
      category,
      selectable,
      filterable,
      sortable,
      selectable_with,
      data_type,
      is_repeated
    WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

You can replace `<INSERT_RESOURCE_OR_FIELD>` in this query with either a
resource (such as `customer` or `campaign`) or field (such as `campaign.id`,
`metrics.impressions`, or `ad_group.id`).

> [!IMPORTANT]
> **Key Point:** Note that there's no `FROM` clause in this query.

For a list of queryable fields, consult the
[`GoogleAdsField` documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsField).

## Version-specific differences

While Google Ads Query Language syntax, clauses, and operators are identical across all supported
Google Ads API versions (v23, v24, v25, and v26), the catalog of queryable resources,
segments, metrics, and reporting behaviors differs by major version. Query
[`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsFieldService) at the target API version
endpoint to inspect the fields and compatibility rules for that version:

- **Final URL expansion asset view:**
  - **Shopping campaign support (v26 and later):** [`final_url_expansion_asset_view`](https://developers.google.com/google-ads/api/fields/v26/final_url_expansion_asset_view) supports Shopping campaigns (`campaign.advertising_channel_type = 'SHOPPING'`) in addition to Performance Max and Search campaigns. For Shopping campaigns, you can select and filter by `ad_group` fields, but you cannot select `asset_group` fields.
  - **Selectable metrics (v25 and later):** Querying [`final_url_expansion_asset_view`](https://developers.google.com/google-ads/api/fields/v26/final_url_expansion_asset_view) returns all selectable metrics for the view. In v24 and earlier, responses include only `metrics.conversions` and `metrics.conversions_value` for Performance Max campaigns and `metrics.impressions` for Search campaigns.
- **Lifecycle goal resources:** In v25 and later, all lifecycle goals (New Customer Acquisition, Customer Retention, and Loyalty Retention) are queried from the unified [`goal`](https://developers.google.com/google-ads/api/fields/v26/goal) and [`campaign_goal_config`](https://developers.google.com/google-ads/api/fields/v26/campaign_goal_config) resources, replacing `customer_lifecycle_goal` and `campaign_lifecycle_goal` (which were used for New Customer Acquisition goals in v24 and earlier, alongside `goal` and `campaign_goal_config` for Customer Retention goals).
- **Shopping product reporting for App campaigns:** In v24 and later, the [`shopping_product`](https://developers.google.com/google-ads/api/fields/v26/shopping_product) resource returns product rows for App campaigns in addition to Shopping, Performance Max, Demand Gen, and Video campaigns (in v23, App campaigns are excluded from `shopping_product` results).
- **Version-specific resources, segments, and metrics:**
  - **v26 and later:** Includes the [`search_lift_keyword_bundle`](https://developers.google.com/google-ads/api/fields/v26/search_lift_keyword_bundle) resource, `campaign.lift_measurement_config`, `local_services_lead.campaign`, `segments.search_lift_keyword_bundle`, `segments.search_property`, and Search Lift metrics (such as `metrics.relative_search_lift`, `metrics.normalized_incremental_searches`, `metrics.search_lift_cost_micros`, and `metrics.search_lift_impressions`).
  - **v25 and later:** Includes lift measurement resources (such as [`lift_measurement_config`](https://developers.google.com/google-ads/api/fields/v26/lift_measurement_config)), segments such as `segments.ad_sub_format_type` and `segments.loyalty_membership`, and YouTube engagement metrics (`metrics.youtube_likes`, `metrics.youtube_comments`, and `metrics.youtube_shares`). Removes `local_services_lead.contact_details.email` (which is selectable in v24 and earlier).
  - **v24 and later:** Includes the [`cart_data_sales_view`](https://developers.google.com/google-ads/api/fields/v26/cart_data_sales_view) resource, `segments.conversion_attribution_event_type` on `shopping_performance_view`, `segments.mobile_device_platform`, and `segments.ad_network_type` on `performance_max_placement_view`. Removes `campaign.video_brand_safety_suitability` (replaced by `customer.video_brand_safety_suitability`), `segments.ad_sub_network_type` on `campaign_budget`, and `segments.click_type` on `ad_group_asset`, `campaign_asset`, and `customer_asset` (which are selectable only in v23).
- **Granular date lookback error code:** Queries that segment by `segments.date`, `segments.week`, or `segments.hour` (or filter on a sub-monthly date range) beyond the 37-month lookback window return `DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED` in v24 and later (or `DateRangeError.UNKNOWN` in v23). See [Date ranges](https://developers.google.com/google-ads/api/docs/query/date-ranges#lookback-limits) for details.

## Code examples

The [client libraries](https://developers.google.com/google-ads/api/docs/client-libs) have examples of using the Google Ads Query Language
in `GoogleAdsService`. The **basic operations** folder has examples such as
`GetCampaigns`, `GetKeywords`, and `SearchForGoogleAdsFields`.