USearch-Cloud Monitor(CMS)-阿里云帮助中心

USearch is an SPL-based query syntax in Cloud Monitor 2.0 that lets you locate entities through full-text search, exact match, and conditional filtering. It integrates with the console through global quick query, quick field drill-down, and metric drill-down.

Using USearch in the console

Global quick query

Log on to the Cloud Monitor 2.0 console, go to a workspace, and in the navigation pane, click Quick Query.

In the search box, enter a query statement (the query part of the USearch SPL syntax), and then click Query. The results are displayed below.
In the left pane, select a domain and an EntitySet, and then click Query. The results are displayed below.
From the results list on the left, select an entity. The details and environment metrics for that entity are displayed on the right.

Entity query

Log on to the Cloud Monitor 2.0 console, go to a workspace, and in the navigation pane, click Entity Explorer.

In the search box, enter a query statement (the query part of the USearch SPL syntax), and then click Query. The results are displayed below. These results are identical to those from a quick query.
Switch to SPL query mode, enter an SPL query statement (using the complete USearch SPL syntax), and then click Query. The results are displayed below.

Quick field drill-down

Log on to the Cloud Monitor 2.0 console and go to the query page or a dashboard for any entity. Hover over a field to display the (USearch) icon. Click the USearch icon. A query box appears, pre-filled with the field's content, and automatically runs a search. The results are identical to those from a quick query.

USearch syntax

USearch supports various query modes and combinations of conditions.

Basic syntax structure

.entity with(
    domain='domain_pattern',     -- Filter by domain
    type='type_pattern',         -- Filter by type
    query='search_query',        -- Query condition
    topk=10,                     -- Maximum number of results to return
    groupTopk=5                  -- Maximum number of results to return for each entity_type
)

Parameters:

Parameter	Type	Required	Description	Example
domain	string	No	Filters by domain and supports wildcard characters.	`'apm'`, `'k8s'`, `''`
type	string	No	Filters by type and supports wildcard characters.	`'apm.service'`, `'*service'`
query	string	No	Specifies the query condition, which supports multiple syntaxes, such as full-text search, phrase search, logical operations, and exact match.	`'error'`, `'name:web-app'`
topk	int	No	The maximum number of results to return. Default: 100.	`50`, `200`
groupTopk	int	No	The maximum number of results to return for each `entity_type`.	`5`, `10`

Query modes

By default, the query statement is split into words by a tokenizer. A full-text search is performed for each word, and the system returns all entities that match and satisfy the logical operations. USearch supports the following query modes:

1. Full-text search

Searches the content of all fields and supports multiple-keyword queries:

-- Simple keyword search
.entity with(query='ecs for rag')

-- Multi-keyword OR query (default behavior)
.entity with(query='kubernetes docker container')

Features:

By default, multiple terms separated by spaces are combined with a logical OR operator.
Searches all fields, including system fields and custom fields.
Automatically tokenizes terms and sorts results based on relevance scores.

2. Phrase search

For hyphenated phrases, all terms must appear consecutively in the same field:

-- Exact phrase match
.entity with(query='cms-cloud-d-user-sls-test-safat-tw7z5zqq-d558c')

Matching rules:

Terms connected by hyphens must appear consecutively in the same field.
The phrase must be fully contained within a single field value. Partial matches of the phrase are not supported.

3. Field-specific search

Performs a tokenized search within a specific field:

-- Basic field search
.entity with(query='desc: ecs-for-rag')

-- System field search
.entity with(query='__entity_id__:web-service-001')

-- Custom field search
.entity with(query='cluster_name:production')

4. Logical condition combinations

You can create complex queries by combining logical operators:

-- AND condition: Meets all conditions
.entity with(query='service_name:web AND status:running')

-- OR condition: Meets any of the conditions
.entity with(query='environment:prod OR environment:staging')

-- NOT condition: Meets the left condition but not the right one
.entity with(query='type:service NOT status:stopped')

-- Complex combination: Use parentheses to control priority
.entity with(query='(cluster:prod OR cluster:staging) AND NOT status:maintenance')

Logical operators:

AND: Matches if both conditions are met.
OR: Matches if either condition is met.
NOT: Matches if the left condition is met but the right one is not.

5. Exact match mode

If you want to query for an exact string match, enclose the string in double quotation marks ". For example, .entity with(query='"<QUYERY_STRING>"'). See the specific example below:

-- Perform an exact match on a specific field
.entity with(query='service_name: "web-server" ')

-- Perform an exact match on all fields by default
.entity with(query=' "aliyun-web-service" ')

-- Combine with AND or OR logical operators
.entity with(query=' cluster: "monitor-k8s" and service_name: "web-server" OR "aliyun-web-service" ')

Important

If the query contains a NOT logical operator, exact match mode is not supported. The query reverts to the default token-based matching.
An "exact match" means a field contains the query string as a substring, not that the field's value is identical to the string. For example, for the query string "service-is-running", the matching results are as follows:
- apm-service-is-running: Match
- apm-service-is-running-on-ack: Match
- apm-service-is-not-running: No match, because it does not contain the query substring.

Handling special characters

If the query content contains special characters, you must enclose it in double quotation marks:

-- Query containing a colon
.entity with(query='description:"ratio is 1:2"')

-- Query containing a pipe symbol
.entity with(query='config:"value1|value2"')

-- Query containing a space
.entity with(query='name:"my service name"')

-- Query containing a comma
.entity with(query='list:"item1,item2,item3"')

-- Query containing a semicolon
.entity with(query='command:"start; stop; restart"')

-- Query containing a backslash
.entity with(query='path:"C:\\Program Files\\App"')

Special characters that require quoting: : ( ) \ [ ] > < = , { } ; | " ' \r \n \t

Important

If a query value contains any of the preceding special characters, you must enclose the entire value in double quotation marks " .
For values that contain double quotation marks, use the \ escape character.
When enclosed in ", an exact match is also performed.

Filtering by domain and type

Wildcard support

You can use wildcard characters for fuzzy matching:

-- Domain filter examples
.entity with(domain='apm')          -- Exact match for the apm domain
.entity with(domain='a*')           -- Match domains that start with 'a'
.entity with(domain='*cs')          -- Match domains that end with 'cs'
.entity with(domain='*')            -- Match all domains

-- Type filter examples
.entity with(type='apm.service')    -- Exact match
.entity with(type='*.service')      -- Match all types that end with 'service'
.entity with(type='apm.*')          -- Match all types under the apm domain

Combined filtering

You can use domain and type filters at the same time:

-- Query for a specific type under a specific domain
.entity with(domain='apm', type='apm.service', query='production')

-- Use a combination of wildcard characters
.entity with(domain='k8s', type='*.pod', query='error')

Query optimization

Performance optimization

Field-specific search: field:value is more efficient than full-text search.
Add domain/type filters: Narrow the query scope.
Set topk appropriately: Avoid returning an excessive number of results.

Query precision

Use exact match and field-specific queries: These provide more accurate results.
Combine multiple conditions: Use the AND operator for precise filtering.
Leverage the NOT operator: Exclude unwanted results to refine your search.

Common query patterns

-- Find services with errors
.entity with(domain='apm', type='apm.service', query='status:error OR status:warning')

-- Find entities in a production environment
.entity with(query='environment:prod AND cluster:production')

Scoring and sorting

Relevance scoring

USearch uses a multi-factor algorithm to calculate the relevance score for each entity based on the query. A higher score indicates greater similarity.

Single-term scoring

The score for a single search term considers the following factors:

Term's inverse document frequency (IDF) weight
- Terms that appear in many data entries are considered less important.
- Terms that appear in fewer data entries are considered more important.
For example, if an entity_id appears only once across all data, its IDF score is the highest. In contrast, a high-frequency term such as "the" appears in many data entries, so its IDF score is lower.
Column weight
- A term is weighted differently based on the column in which it appears.
- Columns such as the primary key (PK) column and the name column have a higher weight.
- Long text columns have a lower weight.
- The weight is calculated using information entropy. This is a scoring method unique to Simple Log Service (SLS).

Multi-term scoring

The scores of multiple search terms are added together.
Supports a combined calculation of term frequency and field weights.
Matches in shorter documents typically receive higher scores.

Sorting rules

Output control parameters

In the with syntax, you can use the following parameters to control the output:

.entity with(
    query='search_term',
    topk=100,           -- Controls the total number of results
    groupTopk=10        -- Controls the maximum number of results for each entity_type
)

Parameters:

topk: Controls the total number of results to return. Default: 100.
groupTopk: Controls the maximum number of results for each entity_type.

Default sorting rules

By default, results are sorted by relevance score in descending order.
If scores are identical, the system sorts the results by timestamp.
You can combine the query with SPL for custom sorting.

Output format

In addition to the raw data, results include two extra fields:

Field	Description	Example
`__score__`	The relevance score of the search.	`1.0`, `0.9`
`__query__`	The query condition that was used.	`query1`

Output example

| __score__ | __query__ | __domain__ | __entity_type__ | ... |
|-----------|-----------|------------|-----------------|-----|
| 1.0       | query1    | domain1    | type1           | ... |
| 0.9       | query1    | domain2    | type2           | ... |

Sort control

-- Default relevance sorting
.entity with(query='web service error', topk=20)

-- Use groupTopk to control the number of results for each type
.entity with(query='kubernetes pod', topk=100, groupTopk=5)

-- Combine with SPL for custom sorting
.entity with(query='kubernetes pod')
| sort __last_observed_time__ desc | limit 50

-- Sort by score to view the most relevant results
.entity with(query='web service')
| sort __score__ desc | limit 10

Common errors and solutions

Syntax errors

Mismatched parentheses.

-- Incorrect example
.entity with(query='(status:error OR status:warning')

-- Correct example
.entity with(query='(status:error OR status:warning)')

Mismatched quotation marks.

-- Incorrect example
.entity with(query='name:"service name')

-- Correct example
.entity with(query='name:"service name"')

No results found

Check whether special characters are correctly quoted.
Confirm that the domain and type filter conditions are correct.
Verify that field names are spelled correctly.

Performance issues

Avoid overly broad wildcard queries.
Use a reasonable value for topk to limit the number of results.
Prioritize field-specific queries over full-text searches.