Search

AI Draft

Retrieve ranked files and passages with the spans that matched.

Build a results interface with ranked files or passages. Choose a retrieval mode, read the spans that matched, and handle empty or incomplete collections.

Before you begin

You need a collection with ready files and a key with search access. This example uses the collection from Get started. It has access control off, so the request omits principals.

Collection content

Checkout stalled because the service exhausted its connection pool.

“checkout connection failures”

1 · /incidents/checkout.txt

Span: chars 0–67

Ranked results · spans

Answer

“Why did checkout stall?”

The service exhausted its connection pool [1].

[1] checkout.txt · chars 0–67

Search returns spans grouped by file or passage. A span names a file and a place in it that your application can open or read.

Send a Search request

POST https://engine.example.com/namespaces/acme/collections/incident-logs:search

POST /namespaces/acme/collections/incident-logs:search HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "query": "checkout requests stall after deployment",
  "mode": "hybrid",
  "interpretation": "literal",
  "result_type": "file",
  "limit": 10
}

200 OK

{
  "request_id": "req_example_search",
  "index_generation": "generation-example",
  "execution": {
    "mode": "hybrid",
    "interpretation": "literal"
  },
  "results": [
    {
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "path": "/incidents/checkout.txt",
      "content_type": "text/plain",
      "rank": 1,
      "score": 0.81,
      "spans": [
        {
          "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
          "unit": "chars",
          "start": 0,
          "end": 67
        }
      ]
    }
  ],
  "timing_ms": {
    "retrieval": 34,
    "total": 47
  },
  "warnings": [],
  "next_cursor": null
}

query must contain a non-space character and is limited to 32,000 characters. limit controls the page size, from 1 to 100. Its default is 10. next_cursor continues the search; null marks the end.

Choose a mode and result type

Option	Use it for
`mode: "hybrid"`	Matching exact words and meaning together, even when the file uses different wording. This is the default.
`mode: "keyword"`	Matching exact words only, such as IDs, codes, and error strings.
`interpretation: "literal"`	Using the supplied query directly. This is the default.
`interpretation: "natural_language"`	Allowing interpretation to extract search text and filters from a sentence.
`result_type: "file"`	One grouped result per matching file. This is the default.
`result_type: "passage"`	Individual matching passages. A file can supply several results.

The selected mode must appear in /info and be enabled in the collection’s processing profile. Natural-language interpretation still returns spans. Use Answer for a written answer.

Render spans

Every result has the same fields. A file result holds spans: the places that matched, best first, at most three. A passage result holds one span in spans. rank is the relevance position. score is a ranking value, not a probability.

Span unit	What `start` and `end` count
`pages`	Pages of a section or a figure of a PDF or an office file, from 1. Page 7 is `start: 7, end: 8`.
`chars`	Unicode code points in the text form of the file, from 0. On a PDF or an office file, the span also has `pages`: the pages that the chars cover, from 1.
`seconds`	Whole seconds of a video or an audio file, from 0.
`file`	The whole file, such as an image. The span has no `start` or `end`.

Every span is [start, end): end is the first unit after the span. A span holds no content. Send up to 50 spans to Read spans, and get one result for each span, in order. include names the parts of each result. text (the default) returns the text of a document, or the transcript lines of a video or an audio file. raw returns the span cut from the file in its own format: a PDF of the pages, the text of a text file or a mail, the image, or a clip. file returns the whole file. With text, raw is cut to the span of the text.

A binary part comes back inline as base64 data until the call reaches its inline limit. Past that, or with delivery: "url", it comes back as a signed url. The result span uses the unit of the content: the text of pages comes back as chars with pages. A large span comes back in parts: next is the body of the next request, with the same include and delivery. Send it until next is null. A span that cannot be read has an error on its own result. The other spans still read. text needs the key’s search action. raw and file also need read.

POST https://engine.example.com/namespaces/acme/collections/incident-logs:read-spans

POST /namespaces/acme/collections/incident-logs:read-spans HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "spans": [
    {
      "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
      "unit": "chars",
      "start": 0,
      "end": 67
    }
  ],
  "include": [
    "text"
  ]
}

200 OK

{
  "request_id": "req_example_read_spans",
  "results": [
    {
      "span": {
        "file_id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3",
        "unit": "chars",
        "start": 0,
        "end": 67
      },
      "content_type": "text/plain",
      "text": "Checkout stalled because the service exhausted its connection pool."
    }
  ],
  "next": null
}

Handle collection states

An empty collection or a query with no matches returns 200 and results: []. A collection with no ready files while indexing returns 409 collection_not_ready. Wait for completion events before another request.

If every file failed, Search returns 200, no results, and a collection_failed warning. Show that warning rather than treating it as proof that the topic is absent. A degraded collection can return results from its ready files.

Add filters and pagination to refine results. For an enforced collection, follow Apply access rules. The Search reference lists every request and response field.

Was this page helpful?

View as Markdown