> ## Documentation Index > Fetch the complete documentation index at: https://docs.brussle.com/llms.txt > Use this file to discover all available pages before exploring further. # Suggest the relations your documents already hold > The attributes that look like relations, found in a sample of the namespace's documents before you declare any. It creates nothing. First, over a sample of up to 1,000 documents, the string attributes with few distinct values (at most 20, some shared by several documents) are candidate kinds. One is taken as the kind and named in `kind.attribute` with its values; the others are listed in `kind.candidates`, since a status or a plan has as few values as a kind. Pass `kind` to take another candidate. Then, for up to 100 sampled documents of each kind, every string attribute whose values name live documents is listed in `relations`: the kind it is on (`from`), the kind its values name (`to`), and how many of its present values resolved. Each element of an array counts as one value, with the arrays' lengths beside them. A value that names the document holding it is a self-reference, counted apart. A value that resolves to a document id is evidence of a possible relation, not proof of one: check it before you declare it on a judgment. Counts are of the sample, not of the namespace. The work is bounded: documents read, attributes examined, ids looked up and bytes read share one budget, reported in `budget`. When a dimension runs out, the response holds what was found so far, with `complete` false and `exhausted` naming the dimension. The same namespace state gives the same sample, so asking again without writing gives the same suggestions. On a template prefix, the sample is one tenant's, named in `tenant`, as an example; ask on another tenant's namespace to see its own. Billed like a query, as `bytes_scanned` in `usage`: the bytes of the documents it reads, the same as `budget.bytes_read.used`, which the fixed budget bounds. On every plan. ## OpenAPI ````yaml /api-reference/openapi.yaml get /namespaces/{ns}/relations/suggest openapi: 3.1.0 info: title: Brussle API version: '1' license: name: Proprietary identifier: LicenseRef-Proprietary description: | The `/v1` contract. It is locked: changes within `/v1` are additive only, and anything breaking is `/v2`. - **Base URL.** `https://api.brussle.com/v1`. - **Evolution.** Response objects may gain fields and enums may gain values. Clients must ignore what they do not know. Request objects reject unknown fields. - **Path segments.** Namespace names (`{ns}`) and document ids (`{id}`) may contain `/`. Send it percent-encoded as `%2F`, so that `acme/prod/tenant_123` is `acme%2Fprod%2Ftenant_123`. - **Templates.** The judgment routes also take a namespace prefix ending in `/*`, such as `acme%2Fprod%2F*`. A judgment created there is a template: every namespace under the prefix inherits it, including ones created later. The most specific matching prefix wins. - **Thresholds are settings.** Named thresholds belong to the judgment, not to a version. They are evaluated at read time against the raw fields, so a change applies at once to every answer, with no recompute and no new version. - **Entity judgments.** A judgment can read the documents that point at the judged one, through `context.related`, and apply only to documents matching `applies_to`. Its answers carry a `watermark`, and creating one that runs `on_change` returns a replay estimate of its monthly cost until you confirm. - **Referenced documents.** A relation can also read the one document the judged document points at, through `join: {theirs: "id", mine: "attributes."}`. A change to what the relation renders of that document re-judges the judged documents that point at it and are inside `freshness.fanout.scope`: a fan-out. - **Relations.** A relation can read other judgments' answers (banded or cut, never summed), up to three judgments deep and never in a cycle, or be a blocking relation over the documents that share a key, which a `choice` can choose among with `options.from`. A recipe can read the document as the judgment last saw it (`context.previous`). A judgment that can fan out confirms its rolling limits once, at create; past them, work is deferred, reads `stale` with an event, and catches up on its own. Nothing waits for a confirm at runtime. Groups keep aggregates per key value for reporting. - **Idempotency.** Every write operation is idempotent by construction: a retried append adds nothing while its values are still in the array, and a retried upsert or patch sets the same content again. Every request that changes something also takes an `Idempotency-Key`, so that creates, activations, backfills, draws and the rest can be retried safely too: a retry with the key gets the first response back, verbatim and marked `Idempotent-Replayed: true`, instead of running again (see the parameter). - **Errors.** Every error is the `Error` envelope; the HTTP status follows the code (see each response). - **Rate limits.** Every response to a request whose key was accepted carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, which count the key's requests a second; a request refused before its key is checked (`unauthorized`, or a route that does not exist) carries neither. A `rate_limited` response adds `Retry-After`, except a daily allowance that is used up, which says when it renews in `details.resets_at` instead. Every `503` carries `Retry-After` too. Reads of one namespace also have a concurrency limit: past 32 gets and queries in flight at once, one more is `rate_limited` with `Retry-After` and `details.concurrent_reads`, whatever the rate-limit headers show. - **Usage.** Every response that bills carries `usage`. Judging is billed per judgment, engine-neutral, by size class: one judgment answered counts by the tokens of its compiled context and its question together, 1 if standard (up to 2,000 tokens), 4 if large (up to 8,000) and 16 if extra-large (up to 32,000, the engine maximum). No response ever carries an engine's price. servers: - url: https://api.brussle.com/v1 security: - apiKey: [] tags: - name: Namespaces description: Namespaces, their settings and cache warming. - name: Documents description: Writes, point reads and queries. - name: Judgments description: >- Judgment definitions, versions, settings, activation, backfill and template detach. - name: Outcomes and calibration description: | Post what actually happened to judged documents, and read how well answers match it: the calibration report, calibrated answers and threshold recommendations. See [calibration](/concepts/calibration). - name: Groups description: > Groups keep aggregates per value of a key attribute, a group-by you declare for reporting; a template's tenant summary publishes each tenant's groups, banded, as a document the platform can judge. - name: Jobs description: >- Backfill, shadow, periodic, deletion, reference index, evaluation export, resync, group build, discovery and simulation jobs. - name: Engines description: The engine registry. - name: Organization description: | Settings of the whole organization: prefixes marked non-production, which the tenant fee and template calibration pools leave out. - name: Subscriptions description: | Saved queries that send an event when a document starts or stops matching: the query's filter grammar, on a namespace or a template prefix, with the fields each event carries. - name: Webhooks description: | Webhook endpoints, the events feed, the delivery log, redelivery and recovery. Every event type and its body is under `webhooks`. Events are delivered at least once, signed as Standard Webhooks, and kept for 30 days. Webhooks are on every plan, and deliveries are not billed; plans set how many endpoints an organization has. paths: /namespaces/{ns}/relations/suggest: parameters: - $ref: '#/components/parameters/NamespaceOrTemplate' get: tags: - Judgments summary: Suggest the relations your documents already hold description: | The attributes that look like relations, found in a sample of the namespace's documents before you declare any. It creates nothing. First, over a sample of up to 1,000 documents, the string attributes with few distinct values (at most 20, some shared by several documents) are candidate kinds. One is taken as the kind and named in `kind.attribute` with its values; the others are listed in `kind.candidates`, since a status or a plan has as few values as a kind. Pass `kind` to take another candidate. Then, for up to 100 sampled documents of each kind, every string attribute whose values name live documents is listed in `relations`: the kind it is on (`from`), the kind its values name (`to`), and how many of its present values resolved. Each element of an array counts as one value, with the arrays' lengths beside them. A value that names the document holding it is a self-reference, counted apart. A value that resolves to a document id is evidence of a possible relation, not proof of one: check it before you declare it on a judgment. Counts are of the sample, not of the namespace. The work is bounded: documents read, attributes examined, ids looked up and bytes read share one budget, reported in `budget`. When a dimension runs out, the response holds what was found so far, with `complete` false and `exhausted` naming the dimension. The same namespace state gives the same sample, so asking again without writing gives the same suggestions. On a template prefix, the sample is one tenant's, named in `tenant`, as an example; ask on another tenant's namespace to see its own. Billed like a query, as `bytes_scanned` in `usage`: the bytes of the documents it reads, the same as `budget.bytes_read.used`, which the fixed budget bounds. On every plan. operationId: suggestRelations parameters: - name: kind in: query required: false description: >- The attribute to take as the kind, one of the candidates. Omitted, the response picks one and names it. schema: type: string minLength: 1 responses: '200': description: >- The suggestions, from a bounded sample; `complete` says whether the budget ran out. headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: $ref: '#/components/schemas/RelationSuggestions' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/Internal' components: parameters: NamespaceOrTemplate: name: ns in: path required: true description: | A namespace name, or a template prefix ending in `/*`, with any `/` sent as `%2F`: `acme%2Fprod%2Ftenant_123` or `acme%2Fprod%2F*`. schema: $ref: '#/components/schemas/NamespaceOrTemplate' headers: RateLimitLimit: description: >- Requests allowed per second for this key. Only on responses to a request whose key was accepted. schema: type: integer minimum: 0 RateLimitRemaining: description: >- Requests left in the current one-second window for this key. It does not count the per-namespace limit on reads in flight. schema: type: integer minimum: 0 RetryAfter: description: Seconds to wait before retrying. schema: type: integer minimum: 0 schemas: RelationSuggestions: type: object description: | The attributes that look like relations, from a bounded sample of documents. A value that resolves to a document id is evidence of a possible relation, not proof of one; nothing is created. required: - tenant - sampled_documents - kind - relations - complete - exhausted - budget - note - usage properties: tenant: type: - string - 'null' description: >- On a template prefix, the tenant namespace whose documents were sampled, as an example. Null on a namespace. sampled_documents: type: integer minimum: 0 description: Documents in the sample. kind: $ref: '#/components/schemas/SuggestedKinds' relations: type: array description: >- Each attribute of each kind whose values resolve to documents, kinds with the most sampled documents first, attributes in name order. items: $ref: '#/components/schemas/SuggestedRelation' complete: type: boolean description: >- False when a budget dimension ran out before every kind and attribute was examined; what was found is still returned. exhausted: description: The budget dimension that ran out. Null when `complete`. oneOf: - type: string enum: - bytes_read - attributes_examined - ids_looked_up - type: 'null' budget: $ref: '#/components/schemas/SuggestionBudget' note: type: string description: >- Says that a resolving value is evidence of a possible relation, not proof, and that nothing was created. usage: $ref: '#/components/schemas/Usage' NamespaceOrTemplate: type: string description: | A namespace name, or a template prefix: a namespace path ending in `/*`, such as `acme/prod/*`, which every namespace under `acme/prod/` inherits judgments from. Up to 256 bytes. Never exactly `.` or `..`, which a URL path can't carry. pattern: ^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$ minLength: 1 maxLength: 256 SuggestedKinds: type: object description: How the sample was split into kinds. required: - attribute - values - candidates properties: attribute: type: - string - 'null' description: >- The attribute taken as the kind. Null when no attribute qualifies, and the sample is treated as one kind. values: type: array description: >- Its values in the sample, most documents first; `value` null counts the documents without it. items: $ref: '#/components/schemas/KindCount' candidates: type: array description: >- The other attributes that could be the kind, each with its values. Pass one as `kind` to take it instead. items: type: object required: - attribute - values properties: attribute: type: string values: type: array items: $ref: '#/components/schemas/KindCount' SuggestedRelation: type: object description: | One attribute, on the sampled documents of one kind, whose values resolve to documents. Every count is of present values, each array element counting once: `resolved`, `self_references` and `unresolved` add up to `sampled_values`. required: - attribute - from - to - resolved - sampled_values - self_references - unresolved - unresolved_examples - resolved_by_kind - documents - array_lengths properties: attribute: type: string from: type: - string - 'null' description: >- The kind of the documents holding the attribute; null for documents without the kind attribute. to: type: - string - 'null' description: >- The kind most of its resolved values name. Null when only self-references resolved, or the documents named have no kind. resolved: type: integer minimum: 0 description: Values naming another live document. sampled_values: type: integer minimum: 0 description: Present values examined, the denominator. self_references: type: integer minimum: 0 description: >- Values naming the document that holds them. An attribute whose values are all self-references holds the document's own id, not a relation. unresolved: type: integer minimum: 0 description: Values naming no live document. unresolved_examples: type: array maxItems: 5 description: Up to 5 distinct values that named no live document. items: type: string resolved_by_kind: type: array description: >- The resolved values by the kind of the document they name, most first. items: type: object required: - kind - resolved properties: kind: type: - string - 'null' resolved: type: integer minimum: 0 documents: type: integer minimum: 0 description: Sampled documents of `from` that hold the attribute, at most 100. array_lengths: description: >- The lengths of its arrays, over the documents holding one. Null when no value is an array. oneOf: - type: object required: - documents - min - max - mean properties: documents: type: integer minimum: 1 min: type: integer minimum: 0 max: type: integer minimum: 0 mean: type: number minimum: 0 - type: 'null' SuggestionBudget: type: object description: What the suggestion spent of each budget dimension. required: - documents_read - attributes_examined - ids_looked_up - bytes_read properties: documents_read: $ref: '#/components/schemas/BudgetSpent' attributes_examined: $ref: '#/components/schemas/BudgetSpent' ids_looked_up: $ref: '#/components/schemas/BudgetSpent' bytes_read: $ref: '#/components/schemas/BudgetSpent' Usage: type: object description: What this response billed. minProperties: 1 properties: bytes_written: type: integer format: int64 minimum: 0 description: | The data the write stores, as compact JSON in UTF-8: its operations' ids and fields, or the outcomes posted. Whitespace and `\u` escapes of non-ASCII text in the request are not counted, nor are `wait_for` and `wait_timeout_ms`, so the same data counts the same however it was encoded. bytes_scanned: type: integer format: int64 minimum: 0 judgment_units: type: integer format: int64 minimum: 0 description: > Judgments billed, each counted by its size class: the tokens of its compiled context and its question together (the question's text, criteria and every option or level) make it standard (up to 2,000 tokens, counts 1), large (up to 8,000, counts 4) or extra-large (up to 32,000, counts 16). They are metered when the answer is recorded, so writes with `wait_for` and reads with `wait_ms` return the answers without their count; it appears in your usage. tokens_evaluated: type: integer format: int64 minimum: 0 deprecated: true description: Never reported. Judging is billed in `judgment_units`. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: type: object description: >- Code-specific detail, such as the scan estimate on a refused query. Every `internal` error has `request_id`. properties: reason: type: string description: > Why, where one code has more than one cause. On `forbidden`, `payment_overdue`: a payment has been unpaid for 14 days, so the organization's keys are read-only until it is paid; reads still work, and paying restores writes within a few minutes. A key that is read-only itself is `forbidden` without a `reason`. On the events feed's `invalid_request`, `cursor_expired`. suggested_context: description: >- On a create without a context recipe, the recipe suggested from the namespace's documents, or null when there are none. oneOf: - $ref: '#/components/schemas/SuggestedContext' - type: 'null' KindCount: type: object required: - value - documents properties: value: type: - string - 'null' documents: type: integer minimum: 0 BudgetSpent: type: object required: - used - limit properties: used: type: integer minimum: 0 limit: type: integer minimum: 0 ErrorCode: type: string description: | HTTP status by code: `invalid_request` 400, `unauthorized` 401, `budget_exceeded` 402, `plan_required` 402, `forbidden` 403, `not_found` 404, `conflict` 409, `too_large` 413, `engine_version_unavailable` 422, `insufficient_labels` 422, `idempotency_key_reused` 422, `rate_limited` 429, `internal` 500, `engine_unavailable` 503, `unavailable` 503. enum: - invalid_request - unauthorized - forbidden - not_found - conflict - too_large - rate_limited - budget_exceeded - plan_required - engine_unavailable - engine_version_unavailable - unavailable - insufficient_labels - idempotency_key_reused - internal SuggestedContext: type: object description: | The recipe suggested for a create without `context`, in the refusal's `details.suggested_context`. From a sample of the documents the definition applies to: it keeps short text, numbers, booleans and small attributes, and leaves out ids, timestamps, links, binary-looking and very long values, and rarely present fields; `excluded` says why for each. `max_tokens` is set to keep the context in the standard size class, at most 2,000. The same documents always give the same recipe. required: - recipe - cost_per_answer - whole_state_cost_per_answer - sampled_documents - excluded properties: recipe: $ref: '#/components/schemas/ContextRecipe' cost_per_answer: type: - number - 'null' minimum: 0 description: >- Mean judgments per answer, counted by size class, over the sample with this recipe and the definition's question. The suggested `max_tokens` is at most 2,000, the standard ceiling, less the question's tokens, so a context that fills it stays standard with its question. whole_state_cost_per_answer: type: - number - 'null' minimum: 0 description: The same with the whole `state`. sampled_documents: type: integer minimum: 1 excluded: type: array description: >- Each path left out, and why, so you can put back what the question needs. items: type: object required: - path - reason properties: path: type: string reason: type: string enum: - id - timestamp - url - binary - long - rare - too_many ContextRecipe: type: object description: | What the engine sees. A create without it is refused with a suggested recipe, unless `use_context` asks for the suggestion or the whole `state`; a version with no recipe sends the whole `state`, subject to the engine limit. additionalProperties: false properties: fields: type: array description: >- Paths included in order, each verbatim or, as a `ClippedPath`, cut to its first `max_chars` characters. items: $ref: '#/components/schemas/RecipeField' last_n: type: object description: Per array path, keep the last n elements. additionalProperties: type: integer minimum: 1 window: type: object description: >- Per array path whose elements have a timestamp field `at`, keep elements within the window. additionalProperties: $ref: '#/components/schemas/Duration' max_tokens: type: integer minimum: 1 description: Hard cap; the compiler truncates from the end of the last field. related: type: object description: > Up to 4 relations, by name: documents in the same namespace that point at the judged one, or the one document it points at. Each renders as a `related.` entry after `fields`, and a write that changes what it renders makes the judged document's answer `pending` until it is judged again (for a referenced document, only inside the re-judge scope; outside it, the answer is `stale` with `stale_reason` `referenced_changed`). minProperties: 1 maxProperties: 4 propertyNames: $ref: '#/components/schemas/Name' additionalProperties: $ref: '#/components/schemas/Relation' previous: $ref: '#/components/schemas/PreviousRecipe' RecipeField: description: >- A `state` or `attributes` path of the judged document, rendered verbatim, or a `ClippedPath`. oneOf: - type: string pattern: ^(state|attributes)(\.[^.]+)+$ - $ref: '#/components/schemas/ClippedPath' Duration: type: string description: A whole number and a unit (`s`, `m`, `h` or `d`), such as `7d` or `1h`. pattern: ^[1-9][0-9]*[smhd]$ Relation: type: object description: > Documents that point at the judged document. They are ordered newest `created_at` first unless `order` says otherwise: `window` keeps those created within the window, the order is applied, then `last_n` keeps the first n. At least one of `last_n` and `window` is required, and at least one of `fields` and `aggregate`. A relation reads at most the newest 1,000 documents, and an `order` sorts within them. With `join: {theirs: "id", mine: "attributes."}` the relation reads the one document the judged document points at, its referenced document, and takes no `window`. With `last_n` (up to 254) it is a named list instead: the attribute holds an array of ids, and the relation reads the documents it names in list order unless `order` says otherwise, each once, at most `last_n` of them. An id that names nothing, or a document outside `match`, renders nothing and is listed in the evaluation's `related_documents` as `unresolved`. An attribute a named list reads holds at most 254 distinct ids. With `join: {theirs: "attributes.", mine: "attributes."}` it is a blocking relation over the documents that share the judged document's key value. It needs `window`, takes `last_n` up to 254 (up to the `options.from` candidate limit when a `choice` chooses among it with `options.from`), and a change to its block re-judges the block's judged documents. `fields`, `aggregate` and `match` may read other judgments' answers (`answers..`), banded or cut, and the newest outcome posted for each related document (`outcomes..value`), shown as posted: the one with the latest `observed_at`, of two at the same time the one posted last, about the document's current life and of the judgment's current answer type. Posting one re-judges the judgments that read it, within their `rolling_limit`. A relation reads at most 4 judgments' answers or outcomes. additionalProperties: false required: - match - join allOf: - description: A relation renders fields or aggregates. if: not: required: - fields then: required: - aggregate - description: >- A relation over the documents that point at the judged one is bounded by `last_n` or `window`. if: properties: join: type: object properties: mine: const: id then: anyOf: - required: - last_n - required: - window - description: A relation that reads the referenced document takes no `window`. if: properties: join: type: object properties: theirs: const: id then: not: required: - window - description: >- A relation that reads the referenced document takes `last_n` up to 254, as a named list. if: properties: join: type: object properties: theirs: const: id then: properties: last_n: type: integer maximum: 254 - description: A blocking relation needs `window`, and reads at most 254 documents. if: properties: join: $ref: '#/components/schemas/BlockingJoin' then: required: - window properties: last_n: type: integer maximum: 254 - description: >- Only a relation over the documents that point at the judged one, or a named list, takes `order`. if: required: - order properties: order: $ref: '#/components/schemas/RelationOrder' then: anyOf: - properties: join: $ref: '#/components/schemas/ReferringJoin' - required: - last_n properties: join: $ref: '#/components/schemas/ReferencedJoin' properties: match: $ref: '#/components/schemas/RelationMatch' description: Which documents the relation reads. join: $ref: '#/components/schemas/RelationJoin' last_n: type: integer minimum: 1 maximum: 1000 description: >- Keep the first n in the relation's order, newest first by default. On a relation that reads a referenced document it makes a named list, keeping the first n documents the list names, in list order unless `order` says otherwise, at most 254; at most 254 on a blocking relation, and at most the `options.from` candidate limit (see Limits) when `options.from` chooses among it. window: $ref: '#/components/schemas/Duration' description: >- Keep documents created within this long before the later of the judged document's newest write and its newest related creation, at the answer's watermark. An edit to an old related document never moves the window. Not on a relation that reads a referenced document. fields: type: array description: >- Paths to include from each document, rendered under `records` in the relation's order. An entry may be a `BandedField`, which renders a number as its band, or a `ClippedPath`, which renders the first `max_chars` characters. An entry may also be a judgment's `answers..value` and `answers..thresholds.` as they are, and its `.p`, `.score` and `.dist.