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

Queries for resource, segment, and metric fields can be sent to the
[`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) `Search` or `SearchStream`
method. To construct a query in Google Ads Query Language, build it using the
[language grammar](https://developers.google.com/google-ads/api/docs/query/grammar). For a general overview of
Google Ads Query Language, see the [Google Ads Query Language overview](https://developers.google.com/google-ads/api/docs/query/overview). A query is
made up of a number of clauses:

- `SELECT`
- `FROM`
- `WHERE`
- `ORDER BY`
- `LIMIT`
- `PARAMETERS`

Clauses use field names, resource names, operators, conditions, and
orderings to help you select the correct data. When combined into a single
query, you can send the request to Google Ads API.

> [!IMPORTANT]
> **Key Point:** The [`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsFieldService) provides a catalog for Google Ads Query Language clients with metadata about all resource fields, segment fields, and metrics, their relationships to each other, and their availability in each clause. Because the set of queryable resources, fields, segments, and metrics varies across major API versions, query `GoogleAdsFieldService` at the endpoint for the API version you are targeting. For more details, refer to the documentation for [`GoogleAdsField`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsField) and [Version-specific differences](https://developers.google.com/google-ads/api/docs/query/overview#version-specific-differences).

## Clauses

The following sections describe the purpose and syntax of each Google Ads Query Language clause.

### SELECT

The `SELECT` clause specifies a set of fields to fetch in the request.
`SELECT` takes a comma-separated list of resource fields, segment fields,
and metrics, returning the values in the response. The `SELECT` clause is
**required** in a query.

The following sample query shows an example of selecting attributes for a given
resource:

    SELECT
      campaign.id,
      campaign.name
    FROM campaign

You can request different field types in a single request, for example:

    SELECT
      campaign.id,
      campaign.name,
      bidding_strategy.id,
      bidding_strategy.name,
      segments.device,
      segments.date,
      metrics.impressions,
      metrics.clicks
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS

- Main resource fields
  - `campaign.id`
  - `campaign.name`
- Attributed resource fields
  - `bidding_strategy.id`
  - `bidding_strategy.name`
- Segment fields
  - `segments.device`
  - `segments.date`
- Metrics
  - `metrics.impressions`
  - `metrics.clicks`

> [!NOTE]
> **Note:** Some fields cannot be selected in the `SELECT` clause because of the following restrictions:

- Querying fields that are not selectable. These fields have their `selectable` metadata attribute marked as `false`.
- Selecting attributes of repeated fields. These fields have their `is_repeated` metadata attribute marked as `true`.
- Selecting fields that are not available for the given resource in the `FROM` clause. Attributes of some resources cannot be selected together, and only a subset of all metrics and segments is available for the resource in the `FROM` clause.
- Selecting segments or metrics that are not compatible with each other. For more information, see [Segmentation](https://developers.google.com/google-ads/api/docs/reporting/segmentation).

Information related to the preceding conditions can be found in our reference
documentation or from `GoogleAdsFieldService`.

### FROM

The `FROM` clause specifies the main resource to return. The
resource in the `FROM` clause defines what fields can be used in all of the
other clauses for the given query. Only a single resource can be specified in
the `FROM` clause. The `FROM` clause is **required** in a query to the
[`GoogleAdsService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService) `Search` or `SearchStream`
method. However, the `FROM` clause should **not** be specified when using
[`GoogleAdsFieldService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsFieldService).

While only one resource can exist in the `FROM` clause for a given query, fields
from attributed resources may be available as well. These resources are
implicitly joined with the resource in the `FROM` clause, so you only need to
add their attributes to the `SELECT` clause to return their values. Not all
resources have attributed resources. In the following example, you can request
both the ad group ID and the campaign ID from ad groups:

    SELECT
      campaign.id,
      ad_group.id
    FROM ad_group

The `resource_name` field of the main resource is always returned.
In the following example, `ad_group.resource_name` is included in the
response despite not being explicitly selected in the query:

    SELECT ad_group.id
    FROM ad_group

The same is true for attributed resources when at least one field is selected.
For example, `campaign.resource_name` is included in the response for the
following query:

    SELECT
      campaign.id,
      ad_group.id
    FROM ad_group

> [!IMPORTANT]
> **Key Point:** If the resource in the `FROM` clause lists another resource as a `segment`, then selecting any attributes of that resource acts as a segment.

### WHERE

The `WHERE` clause specifies conditions to apply when filtering data for the
request. When using the `WHERE` clause, specify one or more conditions
separated by `AND`. Conditions typically follow the pattern
`field_name Operator value` (or use `BETWEEN value AND value`, `IS NULL`, or
`IS NOT NULL`). The `WHERE` clause is **optional** in a query.

The following example uses `WHERE` to return metrics from a given time
period:

    SELECT
      campaign.id,
      campaign.name,
      metrics.impressions
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS

You can combine multiple conditions to filter the data. This example
requests the number of clicks for all campaigns with impressions on mobile in
the last 30 days:

    SELECT
      campaign.id,
      campaign.name,
      segments.device,
      metrics.clicks
    FROM campaign
    WHERE metrics.impressions > 0
      AND segments.device = 'MOBILE'
      AND segments.date DURING LAST_30_DAYS

Segments in the `WHERE` clause must also be in the `SELECT` clause, except for
the following date segments, referred to as *core date segments*:

- `segments.date`
- `segments.week`
- `segments.month`
- `segments.quarter`
- `segments.year`

In the following query, `segments.date` is selected.
Because this segment is a core date segment, you must provide a finite date
range in the `WHERE` clause composed of *core date segments*:

    SELECT
      campaign.id,
      campaign.name,
      segments.date,
      metrics.clicks
    FROM campaign
    WHERE segments.date DURING LAST_30_DAYS

All segments that meet the preceding condition are `segments.date`,
`segments.week`, `segments.month`, `segments.quarter`, and `segments.year`. If
any of these segments are selected, at least one of them must be used in the
`WHERE` clause.

For more details on date filtering, see
[Date ranges](https://developers.google.com/google-ads/api/docs/query/date-ranges).

> [!IMPORTANT]
> **Key Point:** The separator `AND` can only be used between operator conditions (`WHERE segments.device != 'DESKTOP' AND segments.device != 'MOBILE'`), and not within a single operator condition (`WHERE segments.device != 'DESKTOP' AND 'MOBILE'`).

When filtering, keep the case sensitivity of your operator in mind.
For more information, see [Case sensitivity](https://developers.google.com/google-ads/api/docs/query/case-sensitivity).

For a complete list of operators, consult the
[language grammar](https://developers.google.com/google-ads/api/docs/query/grammar).

### ORDER BY

The `ORDER BY` clause specifies the order in which results are
returned. This lets you arrange the data in ascending or descending order
based on a field name. Each ordering is specified as a `field_name` followed by
`ASC` or `DESC`. If neither `ASC` nor `DESC` is specified, the order defaults
to `ASC`. The `ORDER BY` clause is **optional** in a query.

The following query orders the returned campaigns by the number of clicks from
highest to lowest:

    SELECT
      campaign.name,
      metrics.clicks
    FROM campaign
    ORDER BY metrics.clicks DESC

You can specify multiple fields in the `ORDER BY` clause using a comma-separated
list. The ordering occurs in the same sequence as specified in the query.
For example, in this query selecting ad group data, the results are sorted
in ascending order by campaign name, then in descending order by number of
impressions, then in descending order by number of clicks:

    SELECT
      campaign.name,
      ad_group.name,
      metrics.impressions,
      metrics.clicks
    FROM ad_group
    ORDER BY
      campaign.name,
      metrics.impressions DESC,
      metrics.clicks DESC

### LIMIT

The `LIMIT` clause lets you specify the number of results to return.
This is useful if you only need a subset of results.

For example, `LIMIT` can restrict the total number of results for the
following query:

    SELECT
      campaign.name,
      ad_group.name,
      segments.device,
      metrics.impressions
    FROM ad_group
    ORDER BY metrics.impressions DESC
    LIMIT 50

> [!IMPORTANT]
> **Key Point:** `LIMIT` lets you truncate the results. To retrieve large result sets without truncating, use [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) to stream rows or paginate with [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search).

### PARAMETERS

The `PARAMETERS` clause lets you specify meta parameters for the request.
These parameters may impact what kinds of rows are returned.

The following meta parameters are supported:

#### include_drafts

Set `include_drafts` to `true` to return draft entities.
Defaults to `false`.

For example, the following query fetches draft campaigns along with regular
campaigns:

    SELECT campaign.name
    FROM campaign
    PARAMETERS include_drafts = true

#### omit_unselected_resource_names

Set `omit_unselected_resource_names` to `true` to omit the resource name of
each resource type in the response unless explicitly requested in the
`SELECT` clause. Defaults to `false`.

> [!NOTE]
> **Note:** If you plan to use any of the returned objects for update or remove operations, we recommend setting this option to `false` because resources without resource names cannot be used in mutate operations. If you set this option to `true`, make sure you explicitly request the resource names of both the primary resource and any attributed resources you fetch using the query.

| Query | Returned resources |
|---|---|
| ```sql SELECT campaign.name, customer.id FROM campaign ``` | - `campaign.resource_name` - `customer.resource_name` `omit_unselected_resource_names` defaults to `false`, so all `resource_name` fields are returned. |
| ```sql SELECT campaign.name, customer.id FROM campaign PARAMETERS omit_unselected_resource_names = true ``` | None `omit_unselected_resource_names` is specified as `true`, and neither `campaign.resource_name` nor `customer.resource_name` is part of the `SELECT` clause. |
| ```sql SELECT campaign.name, campaign.resource_name FROM campaign PARAMETERS omit_unselected_resource_names = true ``` | - `campaign.resource_name` `omit_unselected_resource_names` is specified as `true`, and `campaign.resource_name` is requested as part of the `SELECT` clause. |

## Additional language rules

In addition to the examples for each clause, Google Ads Query Language supports the following
behaviors:

- The main resource field is **not** required in the `SELECT` clause for a
  query. For example, you can use one or more main resource fields to filter
  data without selecting them:

      SELECT campaign.id
      FROM ad_group
      WHERE ad_group.status = 'PAUSED'

- Metrics can be exclusively selected for a given resource; no other fields
  from the resource are required in the query:

      SELECT
        metrics.impressions,
        metrics.clicks,
        metrics.cost_micros
      FROM campaign

- Segmentation fields can be selected without any accompanying resource fields
  or metrics:

      SELECT segments.device FROM campaign

- The `resource_name` field (`campaign.resource_name`, for example) can be
  used to filter or order data:

      SELECT
        campaign.id,
        campaign.name
      FROM campaign
      WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'