search · Umwelt docs

Reference/Queries/search

searchquerysince 0.1

Finds Facts, Holdings with text and events by their words, their meaning or both, within what the read can see.

Command lineTypeScript.NET

Request

umwelt call story.umw search '{
  "projectId": "ball",
  "text": "roses",
  "filter": { "holder": "bob" }
}'

Request

const result = await client.search({ projectId: 'ball', text: 'roses', filter: { holder: 'bob' } });

Request

var result = engine.Search(new SearchPayload
{
    ProjectId = "ball",
    Text = "roses",
    Filter = new SearchFilter { Holder = "bob" },
});

Response

{
  "items": [
    {
      "docId": "bob-hid",
      "docType": "record",
      "match": "text",
      "record": {
        "kind": "holding",
        "id": "bob-hid",
        "projectId": "ball",
        "timelineId": "main",
        "eventId": "garden",
        "holder": "bob",
        "claim": {
          "subject": "necklace",
          "predicate": "hidden-in",
          "object": { "kind": "entity", "id": "garden" },
          "polarity": true,
          "qualifiers": {}
        },
        "attitude": "knows",
        "confidence": 1.0,
        "accessibility": "available",
        "acquisition": { "kind": "witnessed", "eventId": "garden" },
        "position": { "tick": 2 },
        "provenance": { "origin": { "kind": "human" } },
        "recordedAt": 3,
        "secrecy": { "sharedWith": [] },
        "text": "I buried the necklace under the roses."
      }
    }
  ]
}

Payload

Field	Type	Description
`projectId`required	string	The project to read.
`text`	string	Words to find. At least one of `text` and `semantic` is required; with both, the search is hybrid.
`semantic`	SearchSemantic	A query vector from your model, and the `spaceId` it belongs to.
`at`	Atdefault {}	Where to read: `tick`, an optional `axis`, and `asOfVersion`. Defaults to the latest.
`filter`	SearchFilterdefault {}	`holder`: only that holder’s active, available Holdings. `docType`: `record` or `event`.
`page`	Pagedefault {"limit":100}	How many items to return (`limit`, 1 to 1000) and where to continue (`cursor`, the `nextCursor` of the previous page).
`timelineId`	stringdefault "main"	The timeline to read.

Result

Field	Type	Description
`items`always	SearchItem[]	Matches, best first, each with its `docType`, `docId`, the `record` or `event`, `match` (`text`, `semantic` or `both`) and, by meaning, its `score`.
`nextCursor`	string	More matches follow.

Rules

A match the read cannot see is never returned. The timeline, the position, the status of each record and, with filter.holder, the holder’s own perspective all apply, however well a document matches.

Without a holder, the narrator’s view. Facts and events. Suppressed and inaccessible Holdings are never returned.

Pages can shift. The cursor is an offset: keep the file unchanged while paging, or start again after a write.

Errors

VALIDATION_FAILEDNeither text nor semantic is given, a semantic page reads past 1,000 results, or the vector does not fit the space.

NOT_FOUNDThe project, timeline or embedding space does not exist, or the draft read was purged.

INVALID_STATEThe timeline read is a draft that was promoted. details.promotedInto names the timeline to read instead.

HANDSHAKE_REQUIREDOver the protocol, hello was not sent first.

Every code is listed in Errors.

Payload

Result

Rules

Errors

See also