Save your first object
Build an Omnio instance and try saving, reading, searching, and deleting an object.
What you will build
You will write a small program that saves a text object in Omnio, reads its metadata, runs a semantic search, and deletes it.
The data is stored in the Node.js file system and SQLite, so it remains after the program exits.
1. Create a project
Create an empty directory and install the packages.
mkdir omnio-tutorial
cd omnio-tutorial
pnpm init
pnpm add omnio @omniojs/idx-sqlite.node @omniojs/emb-gemma2 unikvs @unikvs/fs.node valibot @logtape/logtape
pnpm add -D tsx typescript
Add "type": "module" to package.json.
{
"type": "module"
}
2. Construct Omnio
Create src/main.ts and pass an entity store, an index, and an embedder.
import { Gemma2Embedder } from "@omniojs/emb-gemma2";
import { SqliteNodeIndex } from "@omniojs/idx-sqlite.node";
import { NodeFs } from "@unikvs/fs.node";
import { Omnio } from "omnio";
import * as unikvs from "unikvs";
type EntityMapping = Record<string, unikvs.Value<Uint8Array>>;
const omnio = new Omnio({
entity: new unikvs.Builder<EntityMapping>().persist(new NodeFs("./omnio-entities")),
index: new SqliteNodeIndex({ location: "./omnio.sqlite3" }),
embedder: new Gemma2Embedder(),
});
await omnio.open();
try {
// Write operations here.
} finally {
await omnio.close();
}
entity stores the bytes. Pass a unikvs builder configured through persist(). Omnio calls build() in its constructor.
index stores metadata and embedding vectors. SqliteNodeIndex creates the tables it needs when it opens.
embedder turns descriptions into vectors. Gemma2Embedder downloads the model on the first embedding.
3. Save an object
Add the object write inside the try block.
const bytes = new TextEncoder().encode(
"Omnio is a library that adds metadata and embeddings to objects.",
);
const saved = await omnio.putObject({
key: "notes/first.txt",
data: bytes,
contentType: "text/plain",
description: "A note from the first time using Omnio",
tags: ["tutorial", "note"],
userMetadata: { language: "en" },
});
console.log(saved.key.key); // notes/first.txt
console.log(saved.size); // number of bytes written
console.log(saved.tags); // ["tutorial", "note"]
When description is present, Omnio generates an embedding for it by default. key accepts a string or an OmnioKey.
4. Read metadata and bytes
Use headObject for metadata and getObject for the bytes.
const head = await omnio.headObject("notes/first.txt", {
select: {
key: true,
size: true,
tags: true,
description: true,
},
});
console.log(head);
const data = await omnio.getObject("notes/first.txt");
console.log(data === null ? "not found" : new TextDecoder().decode(data));
If you omit select, headObject returns every metadata field. getObject returns the stored bytes unchanged.
5. Search semantically
Find objects whose descriptions are close to a query.
const results = await omnio.searchObjects({
query: { text: "a note from the first time" },
topK: 5,
});
for (const result of results) {
console.log(result.key.key, result.score);
}
searchObjects embeds the query text and compares it with the stored embeddings. Results are ordered by similarity and include a score.
6. List and delete
Filter by tag, then delete the object.
const list = await omnio.listObjects({
filter: { tags: { has: "note" } },
});
console.log(list.items.map((item) => item.key.key));
const deleted = await omnio.deleteObject("notes/first.txt");
console.log(deleted); // true
console.log(await omnio.hasObject("notes/first.txt")); // false
console.log(await omnio.getObject("notes/first.txt")); // null
Deletion is logical. The object disappears from reads and searches immediately, but its bytes are reclaimed in the background after the grace period.
7. Run it
pnpm tsx src/main.ts
The first run downloads the embedding model. Later runs use the cache.
Complete code
import { Gemma2Embedder } from "@omniojs/emb-gemma2";
import { SqliteNodeIndex } from "@omniojs/idx-sqlite.node";
import { NodeFs } from "@unikvs/fs.node";
import { Omnio } from "omnio";
import * as unikvs from "unikvs";
type EntityMapping = Record<string, unikvs.Value<Uint8Array>>;
const omnio = new Omnio({
entity: new unikvs.Builder<EntityMapping>().persist(new NodeFs("./omnio-entities")),
index: new SqliteNodeIndex({ location: "./omnio.sqlite3" }),
embedder: new Gemma2Embedder(),
});
await omnio.open();
try {
const bytes = new TextEncoder().encode(
"Omnio is a library that adds metadata and embeddings to objects.",
);
const saved = await omnio.putObject({
key: "notes/first.txt",
data: bytes,
contentType: "text/plain",
description: "A note from the first time using Omnio",
tags: ["tutorial", "note"],
userMetadata: { language: "en" },
});
console.log(saved.key.key);
console.log(saved.tags);
const head = await omnio.headObject("notes/first.txt", {
select: {
key: true,
size: true,
tags: true,
description: true,
},
});
console.log(head);
const data = await omnio.getObject("notes/first.txt");
console.log(data === null ? "not found" : new TextDecoder().decode(data));
const results = await omnio.searchObjects({
query: { text: "a note from the first time" },
topK: 5,
});
for (const result of results) {
console.log(result.key.key, result.score);
}
const list = await omnio.listObjects({
filter: { tags: { has: "note" } },
});
console.log(list.items.map((item) => item.key.key));
console.log(await omnio.deleteObject("notes/first.txt"));
console.log(await omnio.hasObject("notes/first.txt"));
console.log(await omnio.getObject("notes/first.txt"));
} finally {
await omnio.close();
}
Next steps
In Try semantic search you will save several objects and try filters and image queries. For a production setup, see Choose and configure components.