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.
Authorizations
An organization API key. Keys carry a role (read_write or
read_only) and may be restricted to a namespace prefix such as
acme/*, or to one namespace such as acme/prod/tenant_1. A prefix
matches on a / boundary: acme/prod/tenant_1* covers
acme/prod/tenant_1 and everything under acme/prod/tenant_1/,
never acme/prod/tenant_12.
Path Parameters
A namespace name, or a template prefix ending in /*, with any
/ sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.
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.
1 - 256^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$Query Parameters
The attribute to take as the kind, one of the candidates. Omitted, the response picks one and names it.
1Response
The suggestions, from a bounded sample; complete says whether the budget ran out.
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.
On a template prefix, the tenant namespace whose documents were sampled, as an example. Null on a namespace.
Documents in the sample.
x >= 0How the sample was split into kinds.
Each attribute of each kind whose values resolve to documents, kinds with the most sampled documents first, attributes in name order.
False when a budget dimension ran out before every kind and attribute was examined; what was found is still returned.
The budget dimension that ran out. Null when complete.
bytes_read, attributes_examined, ids_looked_up What the suggestion spent of each budget dimension.
Says that a resolving value is evidence of a possible relation, not proof, and that nothing was created.
What this response billed.