Using project routing to limit 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, CPS 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 API 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"
}
		

Refer to the examples section for more.

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(*)
		

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

The following request creates a named expression called origin-only:

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

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

				PUT _project_routing
					{
"origin-only": { "expression": "_alias:origin" },
"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