> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector Table

> Add, index, and manage records in a vector table

A `VectorTable` is the handle returned by [`db.open()`](/ai/rag/vector-database#opening-a-table). It is where you add records, look them up by id or exact-match fields, and manage indexes. For ranked, query-based retrieval see [Search](/ai/rag/search).

Every method that returns records is typed against your `metadata`, and every record has the shape `{ id, text, metadata }`.

```typescript theme={null}
const table = await db.open("articles");
```

## Adding records

`add()` inserts records. Each record needs an `id`, the `text` to embed and full-text index, and your `metadata` object. The `text` is embedded automatically — you never pass a vector.

```typescript theme={null}
await table.add([
  {
    id: "1",
    text: "An introduction to retrieval-augmented generation systems.",
    metadata: { title: "RAG Intro", category: "AI" },
  },
  {
    id: "2",
    text: "How vector databases store and search embeddings.",
    metadata: { title: "Vector DBs", category: "Database" },
  },
]);
```

`add()` returns the table, so calls can be chained.

## Looking up records

These methods do exact-match lookups (no embedding or ranking). Use them when you already know the id or want rows matching specific field values.

### `findById()`

Returns the single record with the given `id`, or `null` if none matches.

```typescript theme={null}
const article = await table.findById("1");
// { id: "1", text: "...", metadata: { title: "RAG Intro", category: "AI" } } | null
```

Pass `select` to return only certain columns. `id` is always included.

```typescript theme={null}
const article = await table.findById("1", { select: ["title", "category"] });
```

### `findBy()`

Returns records that match an exact-match filter on `metadata` fields. Multiple fields are combined with `AND`; `undefined` values are ignored.

```typescript theme={null}
const articles = await table.findBy(
  { category: "AI" },
  { limit: 20, select: ["title"] },
);
```

| Option   | Type                                   | Default     | Description                                 |
| -------- | -------------------------------------- | ----------- | ------------------------------------------- |
| `limit`  | `number`                               | `10`        | Maximum records to return.                  |
| `select` | `(keyof metadata \| "id" \| "text")[]` | all columns | Columns to return; `id` is always included. |

### `findOneBy()`

Like `findBy()` but returns the first match or `null`.

```typescript theme={null}
const article = await table.findOneBy({ title: "RAG Intro" });
```

<Note>
  In `findBy()` / `findOneBy()`, the keys are your `metadata` field names — the package resolves them to the underlying `metadata.<field>` columns for you. The same applies to `select` and to [filters](/ai/rag/filtering).
</Note>

## Indexing

Tables created by `open()` already carry a btree index on `id`, a full-text index on `text`, and an IVF-PQ index on `vector`. These methods let you add or rebuild indexes — for example a scalar index on a `metadata` field you filter on often.

### `createIndex()`

Creates a scalar index on a column. Choose the index type via `config`: `btree` (range and equality), `bitmap` (low-cardinality categories), or `labelList` (list membership).

```typescript theme={null}
import { Index } from "@lancedb/lancedb";

await table.createIndex("metadata.category", { config: Index.bitmap() });
```

### `createVectorIndex()`

Creates an IVF-PQ vector index. Defaults to the `vector` column.

```typescript theme={null}
await table.createVectorIndex();
// or target a specific column
await table.createVectorIndex("vector");
```

Both methods return the table for chaining.

<Tip>
  Build a scalar index on any `metadata` field you filter on frequently — it lets the query engine skip non-matching rows instead of scanning them, which speeds up both [`findBy()`](#findby) and filtered [search](/ai/rag/search).
</Tip>

## Inspecting query plans

`explainPlan()` and `analyzePlan()` help you tune retrieval — they reveal which indexes are used and where time is spent. See [Search → Inspecting query plans](/ai/rag/search#inspecting-query-plans) for details and examples.