Search collection

Retrieve ranked files or passages, with the spans that matched, from one collection.

POST/namespaces/{namespace}/collections/{collection}:search

PermissionCluster key, or a scoped key with search on this collection. Key scopes and actions.

Search returns spans and never generates an answer. A span holds no content: read it with Read spans. Use Answer for a cited answer.
result_type file (the default) returns one row per file, with up to three spans. passage returns one row per place, with one span, so a file can come back in several rows. Both rows have the same fields.
Pages count from 1: page 7 is start 7, end 8. Chars count Unicode code points from 0, and seconds count from 0. end is the first unit after the span.
hybrid is the default mode. It matches exact words and meaning together. keyword matches exact words only, such as IDs, codes, and error strings. hybrid needs the semantic processing flag. keyword needs the keyword flag.
Empty collections return 200 with no results. When keyword search is not available, a keyword search is 503 temporarily_unavailable, not retryable. Indexing with no ready files returns collection_not_ready. A failed collection returns no results and a warning.
Send principals only when access_control is enforced. No key bypasses the access rules.
Use next_cursor with the same request and key. Search cursors expire after 40 minutes.

Request

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": "database timeout",
  "mode": "hybrid",
  "limit": 10
}

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

Response

200

Ranked files with their spans. Timing and score values are illustrative.

{
  "request_id": "req_example",
  "index_generation": "gen_example",
  "execution": {
    "mode": "hybrid",
    "interpretation": "literal"
  },
  "results": [
    {
      "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
      "path": "/reports/incident.txt",
      "content_type": "text/plain",
      "rank": 1,
      "score": 0.81,
      "spans": [
        {
          "file_id": "fil_01K6Q6N7D8E9F0G1H2J3K4M5N6",
          "unit": "chars",
          "start": 0,
          "end": 77
        }
      ]
    }
  ],
  "timing_ms": {
    "retrieval": 34,
    "total": 47
  },
  "warnings": [],
  "next_cursor": 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

cursorstringoptionalaccepts null

Opaque continuation token from next_cursor. Keep the same key, filters, and other request values. Omit it for the first page.

filterFilterClauseoptionalaccepts null

Structured file selection using built-in fields or the listed metadata fields. Combine clauses with and, or, and not. A metadata key that the collection does not list returns invalid_filter. Filters select data and do not grant or restrict key access.

Maximum depth: 8
Maximum clauses: 100
An in list holds 1–100 values.

interpretationstringoptional

literal uses the supplied search text. natural_language can derive search text and filters from a sentence. It does not generate an answer.

Default: "literal"

literal: Use the supplied search text.
natural_language: Interpret a sentence as search text and filters.

limitintegeroptional

Maximum results in this page. Default 10, minimum 1, maximum 100.

Default: 10

Minimum: 1
Maximum: 100

modestringoptional

hybrid (the default) matches exact words and meaning together. keyword matches exact words only, such as IDs, codes, and error strings. hybrid needs the semantic processing flag. keyword needs the keyword flag.

Default: "hybrid"

keyword: Exact words only, such as IDs, codes, and error strings.
hybrid: Exact words and meaning matched together. The default.

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.

querystringrequired

Search text. Must contain a non-space character. Maximum 32,000 characters.

Minimum characters: 1
Maximum characters: 32000

result_typestringoptional

file returns one row per file with up to three spans. passage returns one row per matching place, with one span. Both rows have the same shape.

Default: "file"

file: Group matching passages by source file.
passage: Return individual matching passages.

Responses

200Success

Ranked files with their spans. Timing and score values are illustrative.

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.

executionobjectrequired

The mode and interpretation of this request.

index_generationstringrequiredaccepts null

Opaque identifier for the searchable generation. It changes when indexed data changes. Null means that no searchable generation exists.

next_cursorstringrequiredaccepts null

Token for the next page, or null when this result has no next page. Do not parse or modify the token.

request_idstringrequired

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

resultsarray<object>required

One row per file with result_type file, or one row per place with result_type passage. An empty array means there are no matching results.

timing_msobjectrequired

Measured retrieval and total durations in milliseconds.

warningsarray<object>required

Nonfatal conditions that help explain the result, such as every file failing to index.

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_filter

A filter uses an unsupported field, operator, value, or nesting structure, or a metadata key that the collection does not list. details.field names the field. details.reason is not_listed, op_not_allowed, or invalid_value for a metadata field.

What to do: Use the documented filter grammar and field-specific value types. List a metadata key with Update metadata fields before you filter on it.

400invalid_cursor

The cursor expired or does not belong to this request and key.

What to do: Restart from the first page. Preserve the same key, filters, and request values when continuing.

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