---
title: "OpenAI"
description: "This section contains information about the OpenAI embeddings feature of SurrealDB."
canonical_url: "https://surrealdb.com/docs/integrate/integrations/embeddings-providers/openai"
section: "Embeddings providers"
surrealdb_version: "4.x"
last_modified: "2026-11-18T02:09:16Z"
---

> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# OpenAI

This section contains information about the OpenAI embeddings feature of SurrealDB.

**Python**

SurrealDB provides a number of different embeddings features that can be used to manage your data. This walkthrough shows how to embed your text with OpenAI, store the vectors in SurrealDB, and run fast k‑nearest‑neighbour (KNN) searches, all from Python. It follows the same flow you might have seen for Qdrant, but swaps in SurrealDB’s native vector‑search features so you can keep documents, graphs, and embeddings in one place.

## Install the two clients

OpenAI calls the API that turns text into a 1 536‑dimensional vector, while SurrealDB lets your Python code connect over WebSocket or HTTP to any SurrealDB server.

SurrealDB must be running somewhere. If you do not have SurrealDB running already you can spin up an in‑memory node in one line:

```bash
pip install openai surrealdb   
```

For local testing you can spin it up quickly:

```bash
docker run -p 8000:8000 surrealdb/surrealdb:latest start --user root --pass secret
```

## Set up the OpenAI and SurrealDB clients

```python
import asyncio
import openai
from surrealdb import Surreal

openai_client = openai.Client(api_key="YOUR_OPENAI_KEY")

TEXTS = [
    "SurrealDB is a multi-model database you can embed anywhere!",
    "Loved by devs who need graphs, documents **and** vector search in one box.",
]

async def init_db() -> Surreal:
    db = Surreal("ws://localhost:8000/rpc")          # change URL if remote
    await db.signin({"username": "root", "password": "secret"})
    await db.use("demo_ns", "demo_db")
    return db
```

## Create the embeddings with OpenAI

`text‑embedding‑3‑small` is compact, cheap, and surprisingly accurate for semantic search. If you need more nuance (or plan to quantise heavily) you can upgrade to `text‑embedding‑3‑large` (3 072 dimensions) at roughly twice the cost.

```python
EMBED_MODEL = "text-embedding-3-small"

emb_resp = openai_client.embeddings.create(
    input=TEXTS,
    model=EMBED_MODEL
)
emb_vectors = [row.embedding for row in emb_resp.data]   # list[list[float]]
```

## Insert the documents into SurrealDB

SurrealDB is schemaless by default, so you can drop JSON directly into a table named article:

*(table `article` with a vector field called `embedding`)*

```python
async def load_documents(db: Surreal):
    docs = [
        {"text": txt, "embedding": vec}
        for txt, vec in zip(TEXTS, emb_vectors)
    ]
    await db.create("article", docs)

asyncio.run(load_documents(asyncio.run(init_db())))
```

## Add a vector index (HNSW)

The Hierarchical Navigable Small World (HNSW) index trades a tiny bit of accuracy for dramatic speed‑ups compared with brute-force scanning; ideal once your table grows beyond a few thousand records. Because HNSW lives in RAM today, index creation is instant but counts against your memory budget.

SurrealQL lets you add the index once; after that inserts are indexed automatically.

```python
async def add_index(db: Surreal):
    await db.query("""
        DEFINE INDEX article_embedding_hnsw 
        ON article
        FIELDS embedding
        HNSW DIMENSION 1536;
    """)

asyncio.run(add_index(asyncio.run(init_db())))
```

The `DIMENSION` must match the length of the OpenAI vectors (1536 in this model).

## Search for the most relevant documents

```python
async def semantic_search(question: str, k: int = 3):
    query_vec = openai_client.embeddings.create(
        input=[question],
        model=EMBED_MODEL
    ).data[0].embedding

    db = await init_db()

    # KNN search: <|k, ef|> - ef is “search breadth”. 100 is a decent default.
    result = await db.query(f"""
        LET $q := {query_vec};

        SELECT id, text,
               vector::distance::knn() AS distance
        FROM article
        WHERE embedding <|{k},100|> $q
        ORDER BY distance;
    """)
    return result[0]['result']

hits = asyncio.run(semantic_search("What’s the best database for unified search?"))
for hit in hits:
    print(hit["distance"], hit["text"])
```

The `vector::distance::knn()` helper returns the exact distance that the KNN operator just computed, so SurrealDB can immediately sort or filter without recalculating.

Two knobs to remember:

- `k` - the number of neighbours you want back.
- `ef` (the second number) - search breadth. Higher values spend more CPU for slightly better accuracy; 100-200 is a safe default.

## (Optional) Binary-quantise the vectors

SurrealDB stores vectors as arrays of floats (`F32` by default) and doesn’t yet expose built-in binary quantisation the way Qdrant does.
If you need ultra-compact storage you can:

1. **Quantise offline** (e.g. convert to `int32` with `numpy`).
2. Store the compressed list in a separate field (`embedding_q32`) and build an index on that instead:

```sql
DEFINE INDEX article_embedding_q32_mt
ON article
FIELDS embedding_q8
HNSW DIMENSION 1536 TYPE I32;
```

This keeps the SurrealDB side simple while you experiment with different quantisers. For more information about vector search in SurrealDB, see the [Vector Search Reference guides](/docs/learn/data-models/vector-search/overview.md).

**Rust**

In Rust, the [async-openai](https://crates.io/crates/async-openai) crate generates the embeddings and the SurrealDB Rust SDK stores and searches them. This section covers the parts that are specific to OpenAI. The tutorial [Implement semantic search in Rust](/docs/learn/tutorials/tutorials/semantic-search-in-rust.md#using-openai) builds the complete program around them: the `document` table and its index, a function that stores each text with its embedding, and a KNN query that finds the closest documents to a search term.

## Setup

Create a new Cargo project with `cargo new project_name`, go into the project folder, and add the dependencies. The `embedding` feature of `async-openai` enables the embeddings API:

```bash
cargo add anyhow async-openai tokio surrealdb --features async-openai/embedding,surrealdb/kv-mem,tokio/macros,tokio/rt-multi-thread
```
<br />

You need an [OpenAI API key](https://platform.openai.com/api-keys). Set it in the `OPENAI_API_KEY` environment variable rather than in the code, and run the program like this:

```bash
OPENAI_API_KEY=whateverthekeyis cargo run
```
<br />

Or like this if you are using PowerShell on Windows:

```powershell
$env:OPENAI_API_KEY = "whateverthekeyis"
cargo run
```
<br />

## Generate an embedding

The program below reads the key once through a `LazyLock`, creates a client that holds it, and asks the [`text-embedding-3-small`](https://platform.openai.com/docs/guides/embeddings/embedding-models) model for the embedding of one sentence.

```rust
use std::sync::LazyLock;

use anyhow::Error;
use async_openai::{Client, config::OpenAIConfig, types::embeddings::CreateEmbeddingRequestArgs};

static KEY: LazyLock<String> = LazyLock::new(|| std::env::var("OPENAI_API_KEY").unwrap());

#[tokio::main]
async fn main() -> Result<(), Error> {
    let config = OpenAIConfig::new().with_api_key(&*KEY);
    let client = Client::with_config(config);

    let request = CreateEmbeddingRequestArgs::default()
        .model("text-embedding-3-small")
        .input("Octopuses solve puzzles and escape enclosures, showing advanced intelligence.")
        .dimensions(1536u32)
        .build()?;
    let mut result = client.embeddings().create(request).await?;

    let embedding: Vec<f32> = result.data.remove(0).embedding;
    println!("{}", embedding.len());
    Ok(())
}
```

```text title="Output"
1536
```

The response holds one `Embedding` for each input, and each one's `embedding` field is a `Vec<f32>`. That type can be stored in SurrealDB as it is, as an `array<float>` field.

## Match the index to the model

`text-embedding-3-small` returns vectors of [1536 dimensions](https://platform.openai.com/docs/guides/embeddings) by default. The `.dimensions()` setting asks the model for shorter vectors, and whatever length you choose, a vector index on the field that stores them must use the same `DIMENSION`. The tutorial uses 1536 for both.

Compared with the Mistral AI client in the [Mistral](/docs/integrate/integrations/embeddings-providers/mistral.md) Rust example, three things change: the model is a string rather than an enum, the request is built with `CreateEmbeddingRequestArgs`, and the index uses `DIMENSION 1536` instead of `DIMENSION 1024`. The table, the structs and the KNN query work unchanged.
