Object Set Service

ObjectSetService manages object sets — named collections of ontology objects defined by stable membership lists, search filters, or set operations. This page covers the read-side endpoints customers need when their workflow is “find an existing object set, list its members, then load those objects.”

Base path: /object-sets

Object set definitions

Every object set has a definition that describes how its members are determined. The runtime supports five definition types, expressed as an ObjectSetDefinition union:

• stable — membership is explicit. The set holds exactly what was put in it.
• filter — membership is computed by evaluating an ObjectSearchFilter. Optionally takes a starting set to filter against.
• operation — membership is the result of a UNION, INTERSECTION, or DIFFERENCE over other object sets.
• linkOperation — membership is the targets reached by following a specific link type from a source set (EXTRACT_TARGET).
• empty — the set has no members.

Read consistency

Read endpoints accept an optional ReadConsistency enum:

• STRONG — forces a refresh of the object set and any dependencies before returning. Slower but always current.
• EVENTUALLY — may return a cached result. Faster but may lag recent writes.

STRONG is the default when no consistency is specified.

Endpoints

searchObjectSets

HTTP: POST /search

Search across object sets by filter. Filters support boolean composition (and, or, not) over field-specific criteria — currently filtering by creator user ID and by title (exact or fuzzy).

Arguments:

• request (SearchObjectSetsRequest, body) — contains:
  • filter (ObjectSetFilter) — a recursive filter union (and, or, not, userId, title).
  • maxPageSize (optional<integer>) — default 50, maximum 500.
  • pagingToken (optional<string>) — token from a previous response to fetch the next page.

Returns: SearchObjectSetsResponse — contains objectSets (a list of ObjectSetMetadata) and an optional pagingToken for the next page.

getObjectSetMetadata

HTTP: GET /{id}/metadata

Get the metadata for an object set by RID. This returns the set’s definition and bookkeeping — not the actual member objects. Use getObjectSetMembers to list members.

Arguments:

• id (ObjectSetId, path) — the set to look up.

Returns: ObjectSetMetadata — contains the set’s id, title, description, definition, scope, immutability and ephemerality flags, creator, and timestamps.

getObjectSetMembers

HTTP: GET /{id}/members

Get the members of an object set, up to the system-configured size limit. For sets larger than the limit, this endpoint returns an ObjectSetTooLarge error — narrow the set with additional filters first.

Arguments:

• id (ObjectSetId, path) — the set to read.
• consistency (optional<ReadConsistency>, query) — STRONG (the default) or EVENTUALLY.

Returns: GetObjectSetMembersResult — contains members (a map from EnvironmentId to a list of ObjectId) and links (a list of ObjectSetLink records, each with a LinkId, source ObjectId, and target ObjectId).

Errors

• ObjectSetNotFound (404) — no object set exists with the given ObjectSetId.
• ObjectSetTooLarge (413) — the set has more members than the system can return in one response. Narrow it with additional filters.