All Products
Search

This Product

    Cloud Monitor:USearch

    Document Center

    Cloud Monitor:USearch

    Last Updated:Dec 03, 2025

    USearch is a Structured Process Language (SPL) syntax in Cloud Monitor 2.0 used for querying entities. It supports multiple query modes, such as full-text index, exact match, and filter conditions. USearch is deeply integrated with Cloud Monitor 2.0 and provides features such as global quick query, quick field drill-down, and metric drill-down.

    Use USearch in the console

    Global quick query

    To use this feature, log on to the Cloud Monitor 2.0 console, go to any workspace, and in the navigation pane on the left, click Quick Query.

    1. In the input box, enter a search statement, which is the query portion of the USearch SPL syntax, and then click Query. The query results are displayed in the results area below.

    2. On the left side, select a Domain and an EntitySet, and then click Query. The query results are displayed in the results area below.

    3. Select an entity from the results list on the left. The details and environment metrics for the entity are displayed on the right.

    Entity query

    To use this feature, log on to the Cloud Monitor 2.0 console, go to any workspace, and in the navigation pane on the left, click Entity Explorer.

    • In the input box, enter a search statement, which is the query portion of the USearch SPL syntax, and then click Query. The query results are displayed in the results area below. The results are the same as the results of the Quick Query feature.

    • Switch to the SPL query mode, enter a complete USearch SPL statement, and then click Query. The query results are displayed in the results area below.

    Quick field drill-down

    To use this feature, log on to the Cloud Monitor 2.0 console and go to the query page or dashboard of any entity. Hover over a field to display the USearch icon image. When you click the USearch icon, the USearch query box appears, automatically populates with the field content, and initiates a search. The results are the same as the results of the Quick Query feature.

    USearch syntax

    USearch provides a powerful and flexible query syntax. It supports various query modes and condition combinations.

    Basic syntax structure

    .entity with(
    domain='domain_pattern',     -- Domain filter
    type='type_pattern',         -- Type filter
    query='search_query',        -- Search condition
    topk=10,                     -- Maximum number of returned entries
    groupTopk=5                  -- Maximum number of returned entries for each entity_type
)

    Parameters:

    Parameter

    Type

    Required

    Description

    Example

    domain

    string

    No

    Filters by domain. Wildcard characters are supported.

    'apm', 'k8s*', '*'

    type

    string

    No

    Filters by type. Wildcard characters are supported.

    'apm.service', '*service'

    query

    string

    No

    The search condition. Multiple syntaxes are supported.

    'error', 'name:web-app'

    topk

    int

    No

    The maximum number of entries to return. The default value is 100.

    50, 200

    groupTopk

    int

    No

    The maximum number of entries to return for each entity_type.

    5, 10

    Query modes explained

    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 words are connected by a logical OR. A match is found if any of the specified words appear in the document.

    • Searches all fields, including system fields and custom fields.

    • Provides automatic tokenization and sorts results based on relevance scores.

    2. Phrase search

    Phrases connected by hyphens must be fully matched within the same field:

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

    Matching rules:

    • Words connected by hyphens must appear consecutively in the same field.

    • The entire phrase must be matched. Partial matches of the phrase are not supported.

    3. Field-specific search

    Performs an exact search in 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

    Supports complex combinations of 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: Requires that both the left and right conditions are met.

    • OR: Requires that either the left or the right condition is met.

    • NOT: Requires that the left condition is met but the right one is not.

    Handle special characters

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

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

-- Query containing a pipe
.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 escaping: : ( ) \ [ ] > < = , { } ; | " ' \r \n \t

    Important

    • If a query value contains any of the special characters listed above, enclose the entire value in double quotation marks (").

    • For values that contain double quotation marks, use a backslash (\) as an escape character.

    Domain and type filtering

    Wildcard support

    Supports fuzzy matching using wildcard characters:

    -- 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 filtering and type filtering at the same time:

    -- Query 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 suggestions

    Performance optimization

    • Use field-specific searches: A search in the field:value format is more efficient than a full-text search.

    • Add domain or type filters: This narrows the query scope.

    • Set topk to a reasonable value: This avoids returning too many results.

    Query precision

    • Use exact matches: Field-specific queries provide more accurate results.

    • Combine multiple conditions: Use the AND condition for precise filtering.

    • Use the NOT condition: This excludes unwanted results.

    Common query patterns

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

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

    Scoring and sorting mechanism

    Relevance scoring

    USearch uses a multi-factor scoring algorithm to calculate the relevance between a query and each row of data. A higher score indicates greater similarity.

    Scoring for a single search term

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

    1. Inverse Document Frequency (IDF) weight of the term

      • The more documents that contain the search term, the lower its importance.

      • The fewer documents that contain the search term, the higher its importance.

      For example, if an entity_id appears only once across all data, its IDF score is the highest. In contrast, a high-frequency word such as "the" appears in many documents, so its IDF score is lower.

    2. Column weight

      • A term has different weights when it appears in different columns.

      • Primary key (PK) columns, Name columns, and similar columns have higher weights.

      • Longer text columns have lower weights.

      • The weight is calculated using the information entropy method. This is a scoring method unique to Simple Log Service (SLS).

    Multi-term scoring strategy

    • The scores of multiple search terms are added together.

    • Supports the calculation of term frequency weights and field weights.

    • Matches in shorter documents usually receive higher scores.

    Sorting rules

    Output control parameters

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

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

    Parameters:

    • topk: Controls the total amount of output data. The default value is 100.

    • groupTopk: Controls the maximum amount of data for each entity_type.

    Default sorting rules

    • By default, results are sorted by relevance score in descending order.

    • If scores are the same, results are sorted by timestamp.

    • Supports custom sorting in combination with SPL.

    Output result format

    In addition to the raw data, the query results include two additional columns:

    Field

    Description

    Example

    __score__

    The relevance score of the search.

    1.0, 0.9

    __query__

    The query condition.

    query1

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

    Sorting control

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

-- Use groupTopk to control the number of items 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

    1. Mismatched parentheses.

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

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

    2. Mismatched quotation marks.

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

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

    No results found

    1. Check whether special characters are correctly escaped.

    2. Confirm that the domain and type filter conditions are correct.

    3. Verify that the field names are spelled correctly.

    Performance issues

    1. Avoid overly broad wildcard queries.

    2. Use a reasonable value for topk to limit the number of results.

    3. Prioritize field-specific queries over full-text searches.