Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

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.

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.

Was this page helpful?