Read spans

Read the content of 1 to 50 spans that Search, Answer, or Research returned, with one result for each span, in order.

POST/namespaces/{namespace}/collections/{collection}:read-spans

PermissionCluster key, or a scoped key with search on this collection. raw and file in include also need read. Key scopes and actions.

include names the parts, and each part fills the result field of the same name. text (the default) is the text of a document, or the speech of a video or audio file as lines with float start and end seconds. text of a video or audio file also holds the words of its lines, one line each. raw is the span cut from the file in its own format: a PDF of only the pages, the text of a text file or a mail, the image, or a clip. file is the whole stored file.
raw and file return original content, so they need the read action. Without it, the call returns forbidden (403) and reads nothing. text needs only search.
raw and file are binary parts: content_type, size_bytes, and either data or url. With delivery inline (the default), a part comes back as base64 data, up to 20 MiB of decoded data a call, in span order. A part past that comes back as a url that works for 15 minutes. With delivery url, every binary part comes back as a url. The raw part of a text file is its text and always comes back inline.
All parts of one result show the same place: the result span. With text, raw is cut to the span of the text. A part that the file has no form for, such as the text of an image, is left out of the result.
One part stops at 50,000 characters of text, 500 pages, or 600 seconds. The result span is the part returned, in the unit of the content, which can differ from the unit of the request: the text of a pages span comes back as chars with pages. next is the body of the next request: the rest of each span that did not fit, with the same include and delivery. Send it with principals until next is null. A span past the end of the file is cut to the file first.
A span that cannot be read has error on its own result, and the other spans still read: not_found (no such file, a deleted file, or a file that the principals cannot read), invalid_span (the span does not fit the file), or content_unavailable (the stored content is missing or cannot be read, and a retry gets the same answer). Pages or a file that hold no text return an empty span with text "". A silent part of a video returns lines [].
Send principals only when access_control is enforced.

Request

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_01K6Q6N7D8E9F0G1H2J3K4M5N6",
      "unit": "pages",
      "start": 1,
      "end": 3
    }
  ],
  "include": [
    "text"
  ]
}

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

The text of pages 1 and 2, as chars with pages. The span fits in one read, so next is null. A larger span returns next: the body of the next read.

{
  "request_id": "req_example",
  "results": [
    {
      "span": {
        "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
        "unit": "chars",
        "start": 0,
        "end": 3920,
        "pages": {
          "start": 1,
          "end": 3
        }
      },
      "content_type": "application/pdf",
      "text": "Incident summary. The checkout service ran out of database connections at 09:12 UTC."
    }
  ],
  "next": null
}

Path parameters

namespacestringrequired

Namespace name or ns_ ID. It must be visible to this key.

collectionstringrequired

Collection name or col_ ID within the namespace. It must be visible to this key.

Request body

deliverystringoptional

How binary parts come back: inline (the default) or url. The raw part of a text file is always inline.

Default: "inline"

inline: Each binary part as base64 data, up to 20 MiB of decoded data a call, in span order. A part past that comes back as a url. The default.
url: Every binary part as a url.

includearray<string>optional

The parts to return for each span. Each part fills the result field of the same name: text (the default), raw, or file. raw and file need the read action.

Minimum items: 1

text: The extracted text: the text of a document, or the speech of a video or audio file, with its lines. The default.
raw: 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: The whole stored file.

principalsarray<string>optionalaccepts null

End-user and group identifiers supplied by your server. Required on enforced collections and invalid when access control is off. An empty list gives no results. Maximum 4,096 entries, each at most 256 UTF-8 bytes.

spansarray<object>required

The spans to read, as Search, Answer, or Research returned them. Each result follows the order of the spans.

Minimum items: 1
Maximum items: 50

Responses

200Success

The text of pages 1 and 2, as chars with pages. The span fits in one read, so next is null. A larger span returns next: the body of the next read.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

nextobjectrequiredaccepts null

The body of the next request: the rest of each span that did not fit, with the same include and delivery, or null. Send it with principals until next is null.

request_idstringrequired

The Engine request ID, also returned in the x-engine-request-id response header.

resultsarray<object>required

One result for each request span, in the same order.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

400invalid_span

A span in the body has a bad shape, such as a pages span that starts at 0.

What to do: Send each span as Search, Answer, or Research returned it. Pages count from 1.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

409collection_not_ready

The collection cannot serve this retrieval request yet.

What to do: Read retryable and details.retry_after_seconds. If processing failed, inspect file errors and correct the source.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown