// Runs a direct SQL query against any BigQuery table and returns results as a formatted table. Use when the question requires counts, aggregations, rankings, or distributions — not when it requires reading document text. Use {project} in the SQL as a placeholder for the GCP project name.
Receives a text question and returns its embedding vector using gemini-embedding-001 via Vertex AI. Use this when you need a semantic embedding for a question — for downstream vector search, similarity comparison, or passing to another tool.
Runs VECTOR_SEARCH against any BigQuery table that has an embedding column. Returns the top-K most semantically similar documents. Use after the embed skill has produced an embedding file. The caller is responsible for supplying the table reference, columns, and any filters.
| name | query |
| description | Runs a direct SQL query against any BigQuery table and returns results as a formatted table. Use when the question requires counts, aggregations, rankings, or distributions — not when it requires reading document text. Use {project} in the SQL as a placeholder for the GCP project name. |
Runs a direct SQL query against BigQuery and prints results as a formatted text table. No embedding required.
python ${CLAUDE_PLUGIN_ROOT}/skills/query/scripts/query.py \
--sql "<SQL query using {project} as project placeholder>"
The script replaces {project} with the active GCP project at runtime.
Use this skill instead of embed + vector-search when the question requires:
Use embed + vector-search when the question requires reading and synthesizing document text.
Dataset: {project}.customer_experience_derived
Tables: kitsune_retrieval_index, zendesk_retrieval_index, knowledge_base_retrieval_index
Date filter columns:
creation_date DATE — use creation_date BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'creation_date TIMESTAMP — use DATE(creation_date) BETWEEN 'YYYY-MM-DD' AND 'YYYY-MM-DD'-- Top topics by volume (Kitsune)
SELECT topic, COUNT(*) AS count
FROM `{project}.customer_experience_derived.kitsune_retrieval_index`
WHERE creation_date BETWEEN '2026-03-24' AND '2026-04-22'
GROUP BY topic ORDER BY count DESC LIMIT 10
-- Top categories by volume (Zendesk)
SELECT category_generated, COUNT(*) AS count
FROM `{project}.customer_experience_derived.zendesk_retrieval_index`
WHERE DATE(creation_date) BETWEEN '2026-03-24' AND '2026-04-22'
GROUP BY category_generated ORDER BY count DESC LIMIT 10
-- Average sentiment by topic (Kitsune only — do not use Zendesk sentiment)
SELECT topic, COUNT(*) AS count, ROUND(AVG(sentiment_score), 2) AS avg_sentiment
FROM `{project}.customer_experience_derived.kitsune_retrieval_index`
WHERE creation_date BETWEEN '2026-03-24' AND '2026-04-22'
GROUP BY topic ORDER BY avg_sentiment ASC LIMIT 10
-- Volume by product (Zendesk)
SELECT product, COUNT(*) AS count
FROM `{project}.customer_experience_derived.zendesk_retrieval_index`
WHERE DATE(creation_date) BETWEEN '2026-03-24' AND '2026-04-22'
GROUP BY product ORDER BY count DESC
A plain-text formatted table:
topic count
------------- -----
site-breakage 142
sync 98
passwords 74
| Symptom | Fix |
|---|---|
Authentication rejected (401) | Run gcloud auth application-default login |
No GCP project configured | Run gcloud config set project <project-id> |
API error | Confirm the project name with DE and re-authenticate |
No results | Check date range, table name, and filter values |