/bydbql

name: bydbql
description: Generate, validate, and optionally execute read-only BanyanDB BydbQL for STREAM, MEASURE, TRACE, and PROPERTY resources. Use when the user asks to query BanyanDB, translate natural language to BydbQL, inspect BanyanDB schema or data, validate BydbQL, or fetch raw BanyanDB records.

BanyanDB BydbQL

Use this skill when the user asks to query BanyanDB, generate BydbQL, translate natural language to BydbQL, inspect BanyanDB data, validate BydbQL, or run read-only BanyanDB queries.

Workflow

1. Read `references/safety.md` before generating, validating, or executing BydbQL. 2. Read `references/syntax.md` when query syntax is needed. 3. Read `references/examples.md` when mapping natural language to BydbQL. 4. Identify the BanyanDB resource type: `STREAM`, `MEASURE`, `TRACE`, or `PROPERTY`. 5. If the group, resource name, or resource type is missing or ambiguous, use `list_groups_schemas`. 6. If the request involves sorting or ranking (`ORDER BY`, `SHOW TOP`, or wording such as "latest", "top", "highest", "lowest", "first", "last"), or you have already fetched schema, call `get_generate_bydbql_prompt` and follow its index-rule guidance. This is required: `get_generate_bydbql_prompt` is the only component that injects the indexed-field list and enforces `ORDER BY` field substitution/omission. `validate_bydbql` is parse-only, so `ORDER BY <non-indexed-field>` validates `true` but fails at execution. 7. Generate exactly one read-only BydbQL statement. When it contains `ORDER BY`, only sort by a field from the indexed-field list returned by `get_generate_bydbql_prompt`; substitute the closest indexed field, or omit `ORDER BY` when no indexed field matches. 8. Call `validate_bydbql` before execution. 9. Execute with `list_resources_bydbql` only when the user asks to run, query, fetch, show, or inspect raw BanyanDB data. 10. If `validate_bydbql` returns `valid=false`, fix the query and validate again before any execution. 11. If execution fails due to a missing group, resource, or schema, use `list_groups_schemas` to discover the correct names and retry only when the correction is clear.

Tool Use

Use the existing BanyanDB MCP tools:

• `list_groups_schemas`: discover groups and resource names for streams, measures, traces, and properties.
• `get_generate_bydbql_prompt`: return the generation prompt text, including the live indexed-field list and the `ORDER BY` index-rule substitution/omission rules. It is the only source of index-rule `ORDER BY` safety.
• `validate_bydbql`: run read-only safety checks and parse-only BydbQL syntax validation. This does not verify group, resource, tag, field, or index-rule existence.
• `list_resources_bydbql`: execute a validated BydbQL statement when data retrieval is requested.

The host model performs natural language to BydbQL translation using these references and live schema discovery. Promote `get_generate_bydbql_prompt` to a required step whenever ranking or sorting is involved (or once schema has been fetched), because it carries the only index-rule `ORDER BY` check; `validate_bydbql` is parse-only and cannot catch a sort on a non-indexed field.

Output

For generation-only BydbQL requests, return the single BydbQL statement and state that it was not executed.

For BydbQL execution requests, show the BydbQL statement, then summarize the returned data or error concisely.