> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/working-with-data/export-compact-artifact.md).

# Export a compact artifact

Export a collection as an ultra-small read-only serve artifact (quantized slab + provenance) and open it on any device.

`save()` persists the full working collection — f32 base, external id map, lexical tokens. When the index itself is the deliverable (ship repo memory to a device, bundle it with a release, serve it read-only), `export_compact()` writes an ultra-small artifact instead: the quantized slab, the partition directory, and the provenance columns — and nothing else.

{% hint style="info" %}
Measured on a 54k-unit repo index: **22.4 MB vs the 110.6 MB f32 save (4.9x)**, open in 41 ms, 0.7 ms median query, top-8 agreement with exact f32 search 0.906.
{% endhint %}

## What the artifact keeps and drops

| Kept                                                        | Dropped                                           |
| ----------------------------------------------------------- | ------------------------------------------------- |
| quantized vector slab (`vectors.i8`)                        | f32 base slab                                     |
| partition directory + remap (`rowids.i64`, `manifest.json`) | external id map (ids come back as internal ints)  |
| provenance columns (`col_*.npy`)                            | lexical tokens (no `mode="lexical"` on artifacts) |

Consequences, all by design: artifacts are **read-only** (mutation raises), **vector search only**, and off-key filters are refused — partition-key (`where` on the `scope_key`) scoping works.

## Export, then open anywhere

{% stepper %}
{% step %}

#### Build the source collection at `dtype="int8"`

Compact export quantizes at seal time — the source collection must be created with `dtype="int8"` so the int8 slab exists to keep.

```python
col = telys.create_collection(
    "repo_symbols",
    dim=emb.profile.dimension,
    partition_by="scope_key",
    embedder=emb,
    dtype="int8",
    filter_columns=["path", "language", "symbol_type"],
)
col.upsert_texts(texts, ids, metadata)
col.compact()
```

{% endstep %}

{% step %}

#### Export the artifact

```python
col.export_compact("./dist/repo_symbols_artifact", mode="int8")
```

`mode="int8"` is the \~4x tier (Mojo i8 scan). `mode="pq"` is the super-large-repo tier (\~32x scan working set: PQ codes + i8 rerank, codebook trained offline, needs `faiss`).
{% endstep %}

{% step %}

#### Open and search on any device

The artifact is self-contained — no engine directory, no id map, no rebuild:

```python
cx = telys.open_compact("./dist/repo_symbols_artifact", embedder=emb)
res = cx.search_text("qualname_under_test", top_k=8, with_metadata=True)
# res["ids"] are internal ints; provenance comes from the columns:
top = res["metadata"][0]          # {"path": ..., "language": ..., "symbol_type": ...}
```

{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Compact export requires the **local runtime** (`TELYS_RUNTIME=local`). The native runtime has no quantized-export path yet and fails closed with a diagnostic rather than writing a wrong-format artifact.
{% endhint %}

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Search by text</strong></td><td>The query paths an opened artifact supports.</td><td><a href="https://docs.telys.ai/working-with-data/search-by-text.md">Search by text</a></td></tr><tr><td><strong>Save &#x26; snapshots</strong></td><td>The full-fidelity persistence path compact export replaces.</td><td><a href="https://docs.telys.ai/working-with-data/snapshots-and-persistence.md">Save &amp; snapshots</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Every file Telys writes and where.</td><td><a href="https://docs.telys.ai/operations/on-disk-layout.md">On-disk layout</a></td></tr></tbody></table>
