Name: alibabacloud-sls-query
Author: aliyun

Alibaba Cloud SLS (Simple Log Service) log query & analysis skill. Use this skill to help users write, explain, optimize, execute, or troubleshoot SLS index search, SQL analytics, and SPL scan/pipeline statements through the aliyun CLI. Triggers: "SLS 查询", "SLS 分析", "日志查询", "日志分析", "log query", "ana

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](references/cli installation guide.md) to install or update. Update Plugins 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 API CLI Action Purpose GetLogsV2 get logs v2 log:GetLogStoreLogs Run query / SQL / SPL and read results GetIndex get index log:GetIndex Read index config to verify prerequisites For the minimum and complete RAM policy JSON, see [references/ram policies.md](references/ram policies.md). Permission failure handling: If a call returns Unauthorized permission error, stop and surface [references/ram policies.md](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. Example (assuming session id is 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. Two sections in the response drive every later decision: Section Meaning line Full text index — absence means full text search is disabled keys Field indexes — map of field → { type, doc value, token, caseSensitive, chn, ... } . doc value: true means statistics are enabled on that field 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](references/related apis.md) and [references/query analysis.md](references/query analysis.md). Step 2: Pick the Query Mode (Critical) The query statement takes one of the following forms: Priority Mode Statement Form Use when Requires 1 Index search <index search Filtering raw logs; return time ordered and paginated logs Full text ( line ) or any field index ( keys.<field ) 2 SQL <index search \ <SQL Aggregation, GROUP BY , sort, window, top N, projection, and other analytical operations Target field has keys.<field with doc value: true 3 SQL scan <index search \ <SQL scan User requested None 4 SPL <index search \ <SPL User requested None 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](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. 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](references/query analysis.md). 3.2 Append SQL — for aggregation / analytics Read [references/query analysis.md](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](references/functions guide.md) for unusual Function selection (aggregate, JSON, regex, datetime, IP geo …) 3.3 Append SPL — for row level processing / flexible filtering For SPL syntax, pipeline commands, and field handling rules, read [references/spl guide.md](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](references/query analysis.md) for scan semantics. 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. 3. Absolute time with explicit timezone — parse using the customer provided timezone or UTC offset. 1. Relative time 2. Natural language absolute time without timezone If the user gives a date/time but no timezone, use the machine's local timezone. First normalize natural language such as 2026年3月13日12点 to 2026 03 13 12:00:00 , then parse it as local time. For a time range such as "2026年3月13日12点到13点", compute both endpoints the same way. For a single point in time request, infer a practical window from the user's intent; if unclear, ask for the range before executing. 3. Absolute time with explicit timezone To convert a local date/time to a Unix timestamp: parse the input as UTC with date u , then subtract the timezone's UTC offset in seconds. Formula: unix ts = date utc parse(input) − (UTC offset hours × 3600) Common UTC offsets (value to subtract): Timezone UTC offset hours Seconds to subtract Beijing (UTC+8) +8 28800 Tokyo (UTC+9) +9 32400 London (UTC) 0 0 New York (UTC 5) 5 18000 Step 5: Execute via get logs v2 Use aliyun sls get logs v2 to execute queries. Run aliyun help sls get logs v2 to see CLI parameter usage; read [references/related apis.md](references/related apis.md) for detailed API parameter descriptions. Required CLI flags: project : SLS project name logstore : Logstore name within the project from : Start of time range, Unix timestamp in seconds (inclusive) to : End of time range, Unix timestamp in seconds (exclusive) query : Statement built in Step 3 Pagination works differently depending on whether the statement has a : 5.1 Index search only — paginate with offset / line Pagination: line is page size ( 1–100 , required); offset is the start row (optional, default 0 ). Ordering: reverse true returns newest first; default false is oldest first. 5.2 With SQL — paginate with LIMIT inside the statement SQL default result cap is 100 rows . To get more results or paginate: LIMIT count — raise the cap (e.g., LIMIT 500 returns up to 500 rows) LIMIT offset, count — paginate (e.g., LIMIT 20, 20 for rows 21–40; LIMIT 40, 20 for rows 41–60). Max offset+count is 1000000. Do not use LIMIT count OFFSET offset syntax — it is not supported . Always use LIMIT offset, count . Ordering: use ORDER BY <field DESC/ASC to sort. Result completeness check: every response contains meta.progress . If it is Incomplete , re issue the same request until it returns Complete . Step 6: Extract Data from the Response get logs v2 returns: Field Meaning meta.progress Complete or Incomplete (see Step 5) meta.count Number of rows returned data Array of log entries or aggregation rows; may contain time (Unix seconds, string) Use jq (preferred) or cli query (JMESPath) to extract the fields the user needs: Extract jq cli query (JMESPath) Data rows \ jq '.data' cli query 'data' Progress \ jq '.meta.progress' cli query 'meta.progress' Row count \ jq '.meta.count' cli query 'meta.count' Specific fields \ jq '.data[] \ {LogStore, read mb}' cli query 'data[].{LogStore: LogStore, read mb: read mb}' Step 7: Present the CLI Command and Results CLI command — always show the full, copy paste ready aliyun sls get logs v2 ... command. Redact any AK/SK. If the query was not executed (write / explain scenario), present the command the user should run. Results — when a query was executed, use Step 6 to extract data and format according to the user's request (table, list, summary, etc.). Append one sentence explaining the query mode choice. Global Rules Always prefer Index search for fastest raw log retrieval, and use Index search + SQL for analysis or field projection. When the user only needs specific fields, use SELECT to project them rather than fetching full raw logs — this reduces network overhead. Requires doc value: true on the target fields (confirmed in Step 1). Do not hard code time filters — pass time range via from / to . Deprecated API : never call get logs ; always use get logs v2 . Troubleshooting When the user reports "no data", "wrong result", or a CLI error, walk through the checklist in this exact order: 1. Time range — wrong from / to ? Milliseconds instead of seconds? Recent writes still indexing? 2. Index configuration — field index missing? Full text index off? Target field not in keys ? 3. Field type / statistics — range query on a text field? SQL on a field without doc value ? 4. Syntax — mixed SQL and SPL? Leading in fuzzy match? SPL string escaping? 5. Mode choice — scanning when an index based query would do? Aggregating in SPL instead of SQL? 6. Completeness — meta.progress = Incomplete , caller did not retry (see Step 5). 7. ProjectNotExist — region or endpoint is wrong. Use cross region discovery to loca