Loading

Using project routing to limit cross-project search scope

Project routing enables you to limit a search to a subset of projects, including the origin project and linked projects, based on tag values.

When you use project routing, the routing decision is made before the search request is performed. Based on the specified tags, cross-project search determines which projects the query is sent to, and the search is performed only on those projects.

For an overview of cross-project search concepts, refer to Cross-project search. For details on available tags, refer to Tags in CPS.

The project_routing parameter is available on all CPS-enabled endpoints. Refer to the supported APIs for a full list of endpoints.

For example, the following request searches the logs resource only on projects that have the _alias:my_search_project tag.

				GET logs/_search
					{
  "project_routing": "_alias:my_search_project"
}

Project routing expressions use Lucene query syntax, so you're not limited to a single tag or an exact match. You can route on any predefined tag, such as _alias, _csp, or _region, or on any custom tag you define in the Elastic Cloud UI. In an expression, the colon (:) separates a tag from its value.

You can combine tags with the AND, OR, and NOT operators and group terms with parentheses. You can also use prefix or suffix wildcards to match part of a tag value. Tag value matching is case-insensitive, so _csp:AWS matches the value aws. Tag names are case-sensitive, so use _csp, not _CSP. The syntax is the same for the _search API and ES|QL.

Note

You can optionally add the _project. prefix to a tag name, for example _project._csp:aws. This is the same prefix used to reference tags in queries. In project routing the prefix is optional, so _csp:aws and _project._csp:aws are equivalent.

For example, the following request routes the search to projects on Amazon Web Services (AWS) in a US region, or to any project on Google Cloud:

				GET logs/_search
					{
  "project_routing": "(_region:us-* AND _csp:aws) OR _csp:gcp"
}
		
SET project_routing="(_region:us-* AND _csp:aws) OR _csp:gcp";
FROM logs
| STATS COUNT(*)

Value matching is case-insensitive. For example, _csp:GCP matches the same projects as _csp:gcp.

Note

Every term in an expression needs a tag name, and every tag must be defined. These expressions fail:

  • _csp:aws OR gcp fails because the bare term gcp has no tag name. Use _csp:aws OR _csp:gcp instead.
  • _foo:bar fails because _foo isn't a defined tag.
  • NOT _csp:azure fails because an expression can't be only a negation. To match every project except Azure, include first and then exclude: _csp:* AND NOT _csp:azure.

Refer to the examples section for more. You can also refer to Query across Serverless projects with ES|QL for more ES|QL examples.

You can define named project routing expressions and reference them in the project_routing parameter of any cross-project search-enabled endpoint that supports project routing.

Named expressions enable you to assign a reusable name to a routing expression. This makes complex routing rules easier to reference and reuse across multiple requests.

To reference a named project routing expression in a project_routing parameter, prefix its name with the @ character.

For example, the following _search API request and ES|QL query search the logs resource only on projects that match the @custom-expression routing rule.

				GET logs/_search
					{
  "project_routing": "@custom-expression",
  "query": { ... }
}
		
SET project_routing="@custom-expression";
FROM logs
| STATS COUNT(*)
Note

Reference a named expression on its own. You can't combine it with a direct expression or with another named expression. Both of these fail:

  • @aws-us-only OR _csp:gcp mixes a named expression with a direct expression.
  • @aws-us-only OR @aws-eu-only combines two named expressions.

You can use the _project_routing API to create and manage named project routing expressions.

Note

Named project routing expressions are project-specific. An expression can be used only in the project where it was created.

The following request creates a named expression called origin-only that matches a single tag:

				PUT _project_routing/origin-only
					{
  "expression": "_alias:_origin"
}

Expressions can be more complex. The following request creates a named expression called aws-us-only that matches AWS projects in a US region:

				PUT _project_routing/aws-us-only
					{
  "expression": "_csp:aws AND _region:us*"
}

You can also create multiple named expressions in a single request:

				PUT _project_routing
					{
  "aws-us-only": { "expression": "_csp:aws AND _region:us*" },
  "aws-eu-only": { "expression": "_csp:aws AND _region:eu*" },
  "linked-security": { "expression": "_alias:*sec*" }
}

The GET _project_routing endpoint retrieves information about named expressions.

To retrieve all named expressions:

				GET _project_routing

To retrieve a specific named expression:

				GET _project_routing/origin-only

To delete a named expression:

				DELETE _project_routing/origin-only
Note

When using the _project_routing API to create, retrieve, or delete expressions, do not prefix the expression name with @. The @ prefix is required only when referencing a named expression in the project_routing parameter of API endpoints that support it.