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

Filter and paginate

Narrow objects with metadata conditions and return pages with a cursor.

List basics

listObjects returns objects in ascending key order. The default limit is 100.

const page = await omnio.listObjects({ limit: 20 });

for (const item of page.items) {
  console.log(item.key.key);
}

console.log(page.nextCursor); // null when there are no more pages

Fetch the next page

Pass nextCursor into the next call.

let cursor: string | null = null;
const all = [];

do {
  const page = await omnio.listObjects({ limit: 100, cursor });

  all.push(...page.items);
  cursor = page.nextCursor;
} while (cursor !== null);

The cursor represents an offset from the beginning. If objects are added or removed while you paginate, items can be duplicated or skipped. Avoid writes during a listing when you need a stable snapshot.

Filter by tag

// Contains one tag
await omnio.listObjects({ filter: { tags: "important" } });

// Contains every tag
await omnio.listObjects({ filter: { tags: { hasEvery: ["work", "2026"] } } });

// Contains any of the tags
await omnio.listObjects({ filter: { tags: { hasSome: ["red", "blue"] } } });

// Has no tags
await omnio.listObjects({ filter: { tags: { isEmpty: true } } });

Tag order does not affect comparison.

Filter by content type

await omnio.listObjects({
  filter: { contentType: "image/jpeg" },
});

await omnio.listObjects({
  filter: {
    contentType: {
      startsWith: "image/",
      not: "image/svg+xml",
    },
  },
});

Content types are lowercased when saved. Filter values are treated as lowercase too.

Filter by size and time

await omnio.listObjects({
  filter: {
    size: { gte: 1024, lt: 10 * 1024 * 1024 },
    createdAt: { gte: new Date("2026-01-01T00:00:00Z") },
    updatedAt: { lt: "2026-12-31T23:59:59Z" },
  },
});

Timestamps accept ISO 8601 strings or Date. Sizes accept numbers and bigint.

Filter by text

fullText performs a substring match against the description and key. It does not tokenize words or rank results.

await omnio.listObjects({
  filter: { fullText: "sunset" },
});

Case sensitivity depends on the database. SQLite ignores case for ASCII, and PostgreSQL uses ILIKE.

Filter by record type

await omnio.listObjects({
  filter: { recordType: "UPDATE_METADATA" },
});

recordType is "CREATE", "UPDATE_METADATA", or "DELETE". Deleted records are always excluded from listings, so filtering by "DELETE" produces an empty result.

Combine conditions

Conditions on the same field must all match, and conditions on different fields are applied together.

await omnio.listObjects({
  filter: {
    contentType: { startsWith: "image/" },
    tags: { hasEvery: ["public", "2026"] },
    size: { lte: 5 * 1024 * 1024 },
    createdAt: { gte: new Date("2026-01-01") },
  },
});

searchObjects accepts the same filter shape. It narrows candidates before similarity is calculated.

await omnio.searchObjects({
  query: { text: "a beach photo" },
  topK: 10,
  filter: {
    contentType: { startsWith: "image/" },
    tags: { has: "public" },
  },
});

Next steps

See Metadata filters for exact types and semantics.

Was this page helpful?