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

Metadata filters

Reference for the MetadataFilter types used by listObjects and searchObjects.

Overview

MetadataFilter narrows the candidates for listings and searches.

type MetadataFilter = {
  contentType?: string | MetadataFilter.Condition;
  createdAt?: string | Date | MetadataFilter.DateCondition;
  fullText?: string;
  hash?: string | MetadataFilter.Condition;
  recordTimestamp?: string | Date | MetadataFilter.DateCondition;
  recordType?: RecordType | MetadataFilter.RecordTypeCondition;
  size?: number | bigint | MetadataFilter.SizeCondition;
  tags?: string | MetadataFilter.TagsCondition;
  updatedAt?: string | Date | MetadataFilter.DateCondition;
};

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

Deleted records are always excluded, regardless of the filter.

String conditions

For contentType and hash, a string means exact equality. The object form supports these conditions.

type Condition = {
  contains?: string;
  endsWith?: string;
  equals?: string;
  in?: readonly string[];
  not?: string;
  notIn?: readonly string[];
  startsWith?: string;
};
Condition Meaning
equals Exact match.
not Not equal.
in Matches any of the values. An empty array matches nothing.
notIn Matches none of the values. An empty array is treated as no condition.
contains Substring match.
startsWith Prefix match.
endsWith Suffix match.

Substring matching uses SQL LIKE or ILIKE. % and _ are escaped.

Date conditions

For createdAt, updatedAt, and recordTimestamp, a string or Date means exact equality. The object form supports these conditions.

type DateCondition = {
  equals?: string | Date;
  gt?: string | Date;
  gte?: string | Date;
  in?: string | Date | readonly (string | Date)[];
  lt?: string | Date;
  lte?: string | Date;
  not?: string | Date;
  notIn?: string | Date | readonly (string | Date)[];
};

Use ISO 8601 timestamps. A Date is normalized to an ISO 8601 string. Deleted records are excluded before conditions apply. Their creation and update timestamps are null, but their record timestamp is the deletion time.

Size conditions

For size, a number or bigint means exact equality. The object form supports these conditions.

type SizeCondition = {
  equals?: number | bigint;
  gt?: number | bigint;
  gte?: number | bigint;
  in?: number | bigint | readonly (number | bigint)[];
  lt?: number | bigint;
  lte?: number | bigint;
  not?: number | bigint | readonly (number | bigint)[];
  notIn?: readonly (number | bigint)[];
};

Tag conditions

For tags, a string requires that tag. The object form supports these conditions.

type TagsCondition = {
  equals?: readonly string[];
  has?: string;
  hasEvery?: readonly string[];
  hasSome?: readonly string[];
  isEmpty?: boolean;
};
Condition Meaning
has Contains the tag.
hasEvery Contains every listed tag.
hasSome Contains any listed tag. An empty array matches nothing.
equals The tag set matches exactly, regardless of order. An empty array means no tags.
isEmpty true requires no tags; false requires at least one.

Record type conditions

recordType is "CREATE", "UPDATE_METADATA", or "DELETE", or an object with these fields.

type RecordTypeCondition = {
  in?: RecordType | readonly RecordType[];
  not?: RecordType | readonly RecordType[];
};

Deleted records are always excluded, so filtering by "DELETE" produces an empty result.

Full text

fullText is a substring match against the description concatenated with the key.

await omnio.listObjects({
  filter: { fullText: "sunset" },
});
  • It does not tokenize, stem, or rank.
  • An empty string is treated as no condition.
  • Case sensitivity depends on the database. SQLite ignores case for ASCII, and PostgreSQL uses ILIKE.

Example

const filter: MetadataFilter = {
  contentType: { startsWith: "image/" },
  createdAt: { gte: new Date("2026-01-01T00:00:00Z") },
  size: { lte: 10 * 1024 * 1024 },
  tags: { hasEvery: ["public", "2026"] },
  recordType: "CREATE",
};

Next steps

Was this page helpful?