Using tags to control search

You can assign tags to projects and use them to control cross-project search behavior.

For an overview of cross-project search concepts, refer to Cross-project search.

CPS supports two kinds of project tags:

• Predefined tags, which are provided by Elastic and describe built-in project metadata.
• Custom tags, which you define and manage to organize projects according to your own needs. These tags are managed in the Elastic Cloud UI.

Only custom tags can be added, modified, or removed. Predefined tags are always available and cannot be changed.

With tags, you can:

• route API calls to specific projects based on tag values
• include tag values in search or ES|QL results to identify which project each document came from
• filter and aggregate results using tags

The following tags are predefined:

• _alias: the project alias
• _csp: the cloud service provider
• _id: the project identifier
• _organization: the organization identifier
• _region: the Cloud region where the project is located
• _type: the project type (Observability, Search, Security)

Predefined tags always start with an underscore _.

There are two ways to use tags in CPS:

• Project routing: limit a search to a subset of projects based on tag values. The routing decision is made before the search is performed.
• Queries: include tag values in search results, or use them to filter, sort, and aggregate results.

You can also use project tags within a search query. In this case, tags are treated as query-time metadata fields, not as routing criteria. You can explicitly request project tags to be included in search results. For both _search and ES|QL, you must request one or more tags to include them in the response.

For example, with the _search endpoint:

				GET logs/_search
					{
  "fields": ["*", "_project.mytag", "_project._region"]
}
		

For example, with ES|QL:

				GET /_query
					{
  "query": "FROM logs METADATA _project._csp, _project._region | ..."
}
		

In both cases, the returned documents include the requested project metadata, which lets you identify which project each document originated from.

You can also use project tags in queries to filter, sort, or aggregate search results. Unlike project routing, using tags inside a query does not affect which projects the query is sent to. It only affects which results are returned. The routing decision has already been made before the query is performed.

For example, the following request aggregates results by cloud service provider:

				GET foo/_search
					{
 "query": { ... }
 "aggs": {
    "myagg": {
      "terms": {
        "field": "_project._csp"
      }
    }
  }
}
		

When you use project tags in ES|QL, you must explicitly include them in the METADATA clause. This is required not only to return tag values in the results, but also to use them in the query for filtering, sorting, or aggregation.

For example, the following ES|QL query counts documents per project alias:

				
					FROM logs* METADATA _project._alias | STATS COUNT(*) by _project._alias