Alibabacloud Sls Query

Alibaba Cloud SLS Query & Analysis

Scenario Description

Use this skill when the user wants to:

• Explain, rewrite, optimize or execute an existing query
• Translate a natural-language requirement into an SLS index query, SQL, or SPL statement

Prerequisites

Install Aliyun CLI

Run aliyun version to verify if version >= 3.3.8. If not installed or outdated, follow the doc references/cli-installation-guide.md to install or update.

Update Plugins

aliyun plugin update

Check Alibaba Cloud credentials configured

Run aliyun configure list to check if credentials configured. If no valid profile is shown, STOP here and ask the user to run aliyun configure outside of this session.

Security rules:

• NEVER read, echo, or print AK/SK values
• NEVER ask the user to paste AK/SK into the conversation
• ONLY use aliyun configure list to check credential status

RAM Permission Requirements

For the minimum and complete RAM policy JSON, see references/ram-policies.md.

Permission failure handling: If a call returns Unauthorized permission error, stop and surface references/ram-policies.md to the user. Do not retry with a different account without explicit user confirmation.

Observability (MUST follow for every aliyun api command)

Upon loading this skill, generate a random session ID (32-char lowercase hex string) once for the entire session. Use it as {session-id} below.

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/{session-id}"

Example (assuming session-id is a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6):

aliyun sls get-logs-v2 --project my-project --logstore my-logstore \
  --from 1740000000 --to 1740003600 --query '*' \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sls-query/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

Core Workflow

1. Read index configuration (GetIndex)
2. Pick query mode
3. Build statement
4. Resolve time range
5. Execute query
6. Extract data from response
7. Present CLI command and results

Step 1: Read the Index Configuration (Mandatory)

Always call get-index first — the index config decides which query modes are available in Step 2.

aliyun sls get-index \
  --project <project> --logstore <logstore>

Two sections in the response drive every later decision:

If the call returns IndexConfigNotExist (HTTP 404), or the response has neither line nor keys populated, the Logstore has no index at all — stop immediately and tell the user they must create an index before any query / SQL / SPL can run.

• The response can be large — extract only the fields relevant to the current query. Cache per logstore and reuse within the session.

For field types, tokenization, and how get-index maps to capabilities, see references/related-apis.md and references/query-analysis.md.

Step 2: Pick the Query Mode (Critical)

The query statement takes one of the following forms:

Selection rule:

• Always prefer Index search for fastest speed.
• Use Index search + SQL when the user needs analytical operations or field projection rather than full raw-log retrieval, such as aggregation, GROUP BY, sorting, window analysis, top-N, or returning only the required fields/columns.
• Do not proactively choose SQL scan or SPL; use them only when the user explicitly requests.

For the full decision guide, see references/query-analysis.md.

Step 3: Write the Statement

3.1 Build the index-search segment first (left of |)

Collect every filter that can be expressed in index-search syntax and place it before the first |. Use * if no filter applies.

* and "payment failed" and status: "500" and not path: "/healthz"

• * matches all; "..." is full-text (needs full-text index).
• key: "value" is a field filter (needs field index).
• Combine with and / or / not; group with parentheses.
• key: * means field exists. Range (>, >=, [a, b]) works only on long / double.

If the requirement can be fully answered without aggregation or row-level processing, stop here — this is already a complete index search. For full index-search syntax, see references/query-analysis.md.

3.2 Append SQL — for aggregation / analytics

status: 500 | SELECT date_trunc('minute', __time__) AS minute,
                    count(*) AS errors
              FROM log
              GROUP BY minute
              ORDER BY minute

• Read references/query-analysis.md for Query & SQL rules
• Table name is log (recommended to omit).
• SQL respects the indexed field type from get-index — a long / double field can be compared directly (status >= 500). Cast only when a field is indexed as text but numeric semantics are needed (try_cast to suppress errors).
• Read references/functions-guide.md for unusual Function selection (aggregate, JSON, regex, datetime, IP geo …)

3.3 Append SPL — for row-level processing / flexible filtering

status: 500 and service: payment
| where try_cast(latency as BIGINT) > 1000
| extend latency_ms = try_cast(latency as BIGINT)
| project service, latency_ms, message

For SPL syntax, pipeline commands, and field-handling rules, read references/spl-guide.md.

3.4 Append SQL scan — fallback when the target field has no index / statistics

Syntax follows regular SQL (see 3.2), with one difference: every field is `varchar`, so always cast() / try_cast() before numeric comparison or arithmetic. See references/query-analysis.md for scan semantics.

* | set session mode=scan; SELECT api, count(1) AS pv FROM log GROUP BY api

Step 4: Resolve the Time Range

Generate --from / --to as Unix timestamps in seconds before building the CLI command. --from is inclusive and --to is exclusive.

Choose one of three input patterns:

1. Relative time — user says "recent / last N minutes|hours|days".
2. Natural-language absolute time without timezone — normalize to YYYY-MM-DD HH:MM:SS, then parse using the machine's local timezone.