--- title: Overview description: Learn how to set up and use the Graphon search and query engine doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Overview Graphon Engine is the search and query engine that powers Graphon Cloud and Graphon Enterprise. This guide introduces its core concepts and shows you how to deploy, set up, and use it. ## What is Graphon Engine? Graphon Engine is a collection of services and storage components that run together as a cluster. The REST API receives requests. The Blob Indexer uses GPUs to understand each file and find connections between files. The Query Engine runs Search and Query. A database holds metadata, a blob cache speeds up data access, and blob storage keeps file content. Blobs are stored units of file data. *Illustration: The main components of a Graphon Engine cluster and how they connect.* ## How Graphon Engine organizes your data *Illustration: How a cluster organizes data: namespaces contain collections, and collections contain files.* A **cluster** is one Engine deployment with its own base URL. It contains **namespaces**, which isolate tenants. A tenant is a customer or application whose data must stay separate. Each namespace contains **collections**. A collection holds the files that one Search or Query request can use. Query can answer a question even when the facts are spread across many files. For example, the `acme-corp` namespace contains an `incident-logs` collection. Add incident reports, screenshots, or recordings to that collection. Search can locate an incident. Query can explain its cause from several reports and cite each source. A file has an ID, a logical path, a source, metadata, and a processing status. Its path might be `/incidents/checkout.txt`. Its source supplies the content. The path organizes the collection and does not have to match the source location. **GET https://graphon.example.com/namespaces/acme-corp/collections/incident-logs/files/fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3** ```http GET /namespaces/acme-corp/collections/incident-logs/files/fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3 HTTP/1.1 Host: graphon.example.com Authorization: Bearer ``` **200 OK** ```json { "id": "fil_01J8Z3K4N5P6Q7R8S9T0V1W2X3", "path": "/incidents/checkout.txt", "status": "ready", "source": { "type": "inline", "content_type": "text/plain", "bytes": 118 }, "metadata": { "environment": "production", "service": "checkout" }, "created_at": "2026-10-06T12:00:00Z", "updated_at": "2026-10-06T12:01:00Z" } ``` ## Adding files to a collection Add a file with one request to the collection’s `files` endpoint. The request names the file’s `path` and its `source`. The source tells Engine where the file bytes come from. *Illustration: Send text inline, upload the bytes, or give a cloud storage URI. Engine adds the file to the collection named in the request path, then moves it from pending to indexing to ready.* | Source | How Engine gets the bytes | | --- | --- | | `inline` | The request body holds the text. Use it for small text files. The whole body must fit in 1,048,576 bytes. | | `upload` | Engine returns a signed `upload.url`. PUT the file bytes to that URL before `upload.expires_at`. | | `uri` | Engine reads the object from your cloud storage, such as a `gs://` URI. Call `/info` to see the URI schemes that your cluster supports. | **POST https://graphon.example.com/namespaces/acme-corp/collections/incident-logs/files** ```http POST /namespaces/acme-corp/collections/incident-logs/files HTTP/1.1 Host: graphon.example.com Authorization: Bearer Content-Type: application/json Idempotency-Key: checkout-txt-1 { "path": "/incidents/checkout.txt", "source": { "type": "inline", "content_type": "text/plain", "text": "Checkout stalled because the service exhausted its connection pool. Increase the pool size before the next deployment." } } ``` Engine replies right away. Inline and URI requests return `202 Accepted`. An upload returns `201 Created` with the upload URL. Each response holds the new file and a job. Save their IDs. Processing continues after the response. The file starts as `pending` while it waits for its bytes or an indexer. During `indexing`, GPUs understand the file’s contents and link it to related files. A `ready` file can appear in Search and Query. If processing stops, the file is `failed`. Read its error and its job. Engine sends a `file.status_changed` event at each change. [Jobs and events](/engine/concepts/jobs) explain how to track completion. ## Searching and querying collections *Illustration: Search ranks the files in one collection. Each result has a rank, path, score, and evidence.* *Illustration: Query answers a natural-language question from several files in one collection. Each citation marker in the answer maps to a source.* | Use | Result | Example | | --- | --- | --- | | Search | Ranked files or passages, scores, and evidence. | Find reports about checkout connection failures. | | Query | An answer grounded in the collection, with citations. | Why did checkout stall, and what should we change? | Both operations address one collection. Choose [Search](/engine/guides/search) to build a results interface. Choose [Query](/engine/guides/query) to answer a question from the files. ## Control who can retrieve An API key authorizes your application. Its scope identifies the namespace or collections it can reach. Its actions identify the operations it can perform. [Authentication](/engine/reference/authentication) explains the complete contract. For per-user retrieval, enable access control on a collection. Your application authenticates each person and sends their **principals**: exact user and group names. Engine applies access rules before content can enter Search results or Query answers. See [Principals and access rules](/engine/concepts/access). ## Start building Use the [Get started guide](/engine/get-started) for a complete HTTP walkthrough with inline text. It requires a reachable cluster and a cluster API key. No external storage account is needed. Read [Concepts](/engine/concepts) for the data model. Use the [API reference](/engine/reference) for request fields, response fields, errors, and examples. Each example uses `https://engine.example.com`; replace it with your cluster URL. ## Sitemap See the full [sitemap](/sitemap.md) for all pages.