--- title: Concepts description: The core Graphon ideas: workspace, bucket, object, tenant partition, the query modes, and datasets. doc_version: 0.1.0-preview last_updated: 2026-09-14 --- # Concepts Think of Graphon as a home for your application’s files. A workspace brings your team and credentials together. Buckets organize the files, objects hold the content, and search turns that content into useful context. ## Workspace The shared home for your team and its data. A workspace owns buckets, API keys, and memberships. Select a workspace before you create a bucket or issue a key. A person can belong to more than one workspace, with a different role in each. Members use roles such as Viewer, Editor, and Admin. API keys also have roles and belong to a workspace. For example, your support team can share a workspace while a backend service uses a workspace key to access its buckets. One workspace contains the team, credentials, and buckets that belong together. An API key applies within its workspace. [Understand API keys and roles](/guides/authentication.md) ## Bucket A named container for related objects. A bucket groups objects in a workspace, much like an S3 bucket. You choose its provider and location when you create it. Separate buckets can hold support files, product media, or data for different customers. Bucket names are case-sensitive and unique within a workspace. Use 1–255 ASCII letters, digits, periods, underscores, or hyphens, except the exact names `.` and `..`. Rename preserves the bucket ID and data. JSON addresses that ID. S3 uses the current name on your workspace endpoint. The bucket’s indexing setting controls whether Graphon indexes its objects. With indexing enabled, Graphon prepares the content for search and query as objects arrive. With indexing disabled, the bucket provides object storage only. Choose this setting when you create the bucket. You cannot change it later. The original file stays in object storage. A bucket with indexing enabled also prepares an index from its content. [Create your first bucket](/guides/store-objects.md) ## Object The file you store, identified by a key inside a bucket. An object combines file bytes with a key, such as `policies/refunds.pdf`. The key identifies the object within its bucket. The same key can exist in another bucket without referring to the same file. Keys can contain slashes to organize related files under a prefix. For example, `policies/` groups policy documents without creating a separate bucket. Objects can hold documents, images, audio, video, or structured records. Store, read, and list them through the API, CLI, or supported S3 operations. To identify this object, use both the bucket and its key. The prefix is part of the key, not a separate storage container. [Explore the object API](/api/objects/list-objects.md) ## Indexing status How far each file has come on its way into search. In a bucket with indexing enabled, each object version has an indexing status. A new version goes through four unfinished states in order. In `preparing`, Graphon copies the file for the index. In `sending`, Graphon gives the file to the index. In `queued`, the file waits for an index worker. In `indexing`, the index reads the content and builds the index. The version then stops in one of three finished states: `ready`, `failed`, or `unsupported`. A `ready` version is searchable. A `failed` version stopped with an error, such as a file that is not a readable PDF. An `unsupported` version is one that Graphon does not index, for example because of its size or its metadata. When a step fails for a short time, Graphon tries it again by itself. The status then shows the number of retries and the last error. When you write a new version of a key, a read returns the new file at once. Search keeps the older ready version until the new version is ready. If the new version fails, search keeps the older version. The `searchable` field names the version that search uses now. Every object response has the status in its `indexing` field. Get bucket index status returns the counts for a bucket and lists its unfinished versions in the order they will finish. With a filter, it lists the failed or unsupported versions with the reason for each. The Objects and Indexing tabs in the app and `graphon buckets index-status` show the same information. A new version moves left to right. While it is unfinished, search still returns the older ready version of the same key. [Read the bucket index status API](/api/objects/get-bucket-index-status.md) ## Tenant partition A way to organize data by the customers of your application. A tenant is your application’s customer or organization. If your support app serves Acme and Northwind, each customer should see only its own files. This boundary is different from a Graphon workspace, which can serve your whole application. Use a key prefix per tenant in one bucket, or a separate bucket per tenant. Your backend checks the signed-in customer and selects the correct prefix or bucket. A prefix is an organization convention, not an access control by itself. Keep the workspace API key in your backend, because it can access other buckets in that workspace. The backend authorizes the customer before it chooses a data path. Separate buckets offer another way to organize each tenant’s data. [Choose a tenant isolation model](/guides/tenant-isolation.md) ## Query modes Choose between finding content and getting an answer from it. A search result helps your application find relevant material. An answer uses that material to respond to a question. Choose the result that your user or agent needs: matching content, passages for a prompt, or an answer with sources. All four run against one target, a bucket with indexing enabled or a dataset, and each is one call on the Graphon API. Search and Answer return on the same call and store nothing. Research returns a run that stays readable until expiresAt, seven days past the end. ### Search for objects Rank the objects of a bucket against a text, and get the places inside each one that matched. One call matches the exact words and the meaning together. POST /search with resultType object → Ranked objects, each with up to 3 spans ### Search for passages The same call, returning one result for each place that matched. Use it to build the context for your own agent or model. POST /search with resultType passage → Ranked passages for a prompt ### Answer a question Ask a question and receive a written answer on the same call, with a citation marker for each source it used. POST /answer → An answer with citations ### Research a bucket Run a question that needs many reads. The run works on its own for minutes, reports each step, and ends with an answer and its sources. POST /research → A run you follow, then a cited answer The same indexed content supports different outputs. [Search your objects](/guides/search.md) ## Citations A connection between an answer and the content that supports it. A citation identifies the source behind a statement in an answer. It lets the reader return to the original object and inspect the supporting content. This is useful when an answer combines information from several files. For example, an answer about refund timing can cite the refund policy instead of leaving the reader to guess where the claim came from. In your application, show the cited source alongside the answer so a reader can check its context. A source reference helps someone verify a claim; it does not replace that review. Graphon writes each citation as a marker such as [[SRC:0001]] inside the answer. The source with the same ref carries the object key, the version that was read, and the place inside it, so a link can open the file at its page or its time range. A source marked as not cited was read but not used. Illustration: the marker [[SRC:0001]] connects the refund timing in the answer to the matching passage in the source document. [Answer a question](/guides/answer.md) ## Dataset A read-only set of documents that Graphon curates and every workspace can query. A dataset holds documents that Graphon curates from a public source, such as court opinions or product pages. Graphon keeps the documents indexed. Your workspace uploads nothing, and a dataset counts toward none of its storage. Query a dataset with the same calls as a bucket. Send its id, which starts with `dst`, as `target` in place of a bucket id, which starts with `bkt`. A dataset query counts toward your plan’s queries per month. A dataset is free, or paid with a monthly price of its own. One call reads one target. The prefix of the id says whether it is a bucket of your workspace or a dataset of the Graphon catalog. [Learn about datasets](/datasets.md) ## Sitemap See the full [sitemap](/sitemap.md) for all pages.