// 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 | vector-search |
| description | 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. |
Queries any BigQuery table using a pre-computed embedding vector and returns the closest matching documents via cosine similarity.
python ${CLAUDE_PLUGIN_ROOT}/skills/vector-search/scripts/vector_search.py \
--embedding-file /tmp/embedding.json \
--table dataset.table_name \
[--embedding-column embedding] \
[--columns col1,col2,...] \
[--label "Display Name"] \
[--date-column COLUMN] \
[--s YYYY-MM-DD] [--e YYYY-MM-DD] \
[--filter column:value] \
[--top-k 5]
| Flag | Required | Description |
|---|---|---|
--embedding-file | yes | Path to the JSON embedding file produced by the embed skill |
--table | yes | BigQuery table as dataset.table (project from gcloud) or project.dataset.table |
--embedding-column | no | Name of the embedding column (default: embedding) |
--columns | no | Comma-separated columns to return (default: all columns) |
--label | no | Display name for the results header (default: table name) |
--date-column | no | Column to apply --s / --e date filters against |
--s | no | Start date filter YYYY-MM-DD (requires --date-column) |
--e | no | End date filter YYYY-MM-DD (requires --date-column) |
--filter | no | Partial-match filter as column:value. Repeatable. |
--top-k | no | Number of results to return (default: 5) |
Formatted context block printed to stdout:
=== Display Name (5 results) ===
[1]
column_a: value
column_b: value
distance: 0.28
...
# Step 1 — embed the question
python ${CLAUDE_PLUGIN_ROOT}/skills/embed/scripts/embed.py \
--question "What are users saying about Firefox sync?" \
> /tmp/embedding.json
# Step 2 — search a table
python ${CLAUDE_PLUGIN_ROOT}/skills/vector-search/scripts/vector_search.py \
--embedding-file /tmp/embedding.json \
--table my_dataset.my_index_table \
--columns title,content,created_at \
--label "My Source" \
--date-column created_at \
--s 2026-01-01 --e 2026-03-31 \
--filter "product:Firefox" \
--filter "locale:es"
| Symptom | Fix |
|---|---|
Authentication rejected (401) | Run gcloud auth application-default login |
No GCP project configured | Run gcloud config set project <project-id> |
Failed to read embedding file | Check the path; ensure embed skill ran successfully |
Invalid --filter format | Use column:value — no spaces around the colon |
No results found | Broaden date range, remove filters, or increase --top-k |
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 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.