# Run semantic search on embeddings from SQL

Source: https://www.hotdata.dev/use-cases/vector-search
Site index: https://www.hotdata.dev/llms.txt

Semantic search doesn't have to mean another database. Keep embeddings in the workspace, build vector indexes, and run nearest-neighbor queries beside ordinary SQL. Similarity scores and relational filters stay in one place.

## How it works

### Step 1: Pick a table and text or vector column

**Claude**

```
Open the help articles table in our support KB and show the columns. I need to pick which field to use for meaning-based search.
```

**CLI**

```bash
hotdata databases tables show support.public.help_articles
```

**Python SDK**

```python
import hotdata

api = hotdata.InformationSchemaApi(api_client)
api.information_schema(
    connection_id="support",
    var_schema="public",
    table="help_articles",
    include_columns=True,
)
```

### Step 2: Create a vector index

**Claude**

```
Index article bodies for semantic (meaning-based) search, using cosine to compare how close two pieces of text are.
```

**Python SDK**

```python
import hotdata

indexes = hotdata.IndexesApi(api_client)
indexes.create_index(
    "support",
    "public",
    "help_articles",
    hotdata.CreateIndexRequest(
        index_name="help_body_semantic",
        index_type="vector",
        columns=["body"],
        metric="cosine",
    ),
)
```

With **`--async`**, the build runs as a background **job**. Embedding and index materialization can take a while, so poll **`hotdata jobs`** until it's done.

### Step 3: Search from the CLI with an embedding model

**Claude**

```
Ask in plain language how refunds work and return the ~10 help articles that best match the question by meaning.
```

**CLI**

```bash
hotdata search "how do I get a refund on my subscription" \
  --index help_body_semantic \
  --select id,title,body \
  --limit 10
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT id, title, body, _distance FROM vector_search("
            "'support.public.help_articles', 'body', "
            "'how do I get a refund on my subscription', 50) LIMIT 10"
        ),
    ),
)
```

### Step 4: Same retrieval in SQL

**Claude**

```
Do that kind of search in SQL: closest matches first, with id, title, and how far each row is from the question. Limit to 10 rows.
```

**CLI**

```bash
hotdata query "SELECT id, title, body, _distance FROM vector_search('support.public.help_articles', 'body', 'onboarding and first invoice', 50) ORDER BY _distance ASC LIMIT 10"
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT id, title, body, _distance FROM vector_search("
            "'support.public.help_articles', 'body', "
            "'onboarding and first invoice', 50) ORDER BY _distance ASC LIMIT 10"
        ),
    ),
)
```

When your **`ORDER BY … LIMIT`** lines up with HNSW and the index is ready, the planner can skip scanning the whole table. If not, distances still compute. They are just slower without the shortcut.

## Who uses this

- Support and docs search ranked by meaning, not just keywords.
- Product catalogs mixing similarity with inventory, pricing, or eligibility filters.
- Agents that need nearest-neighbor rows with distance metadata on the same path as other SQL.