MyJackfruit

Help
Browse topics · Reading and writing records

Reading and writing records

← Back to How do places work (mentions, poses, claims)?

How do I search (find) by text, attribute or place?

Short answer

Search words with GET /base/search naming the vault, find an exact value with GET /base/find-by-attribute, and find by place with GET /base/spatial.

Before you start

Your app holds a person's sign-in token and the key it is bound to. You know the address of the vault to search.

Words used here (4)
sign-in token
A sign-in token is the credential GilbPlatform issues when a person signs in; your app presents it, with a proof, on each request.
vault's address
A vault's address is the web address that names one vault, made from the vault's name, such as https://example-name.gilb.com/vault.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
geometry literal
A geometry literal is the shape of a thing on the map, written as text such as SRID=4326;POINT(10.75 59.91): a point, line or area.
Steps
  1. Search a vault's text with GET /base/search.

    Send the words as q and the vault's address as vault:
    GET https://id.gilb.com/base/search?q=<words>&vault=<the vault's address>

    More about this

    A search that names no vault searches the vault of the host you call, and on https://id.gilb.com it searches your own vault. A search answers only record addresses (ids), 20 a page, never the records; read each one at its address. It finds a whole word in any text of a record; match=prefix also finds words that begin with what you typed and adds each record's label. type=<Name>, the bare type name, keeps one type and may repeat. Send the token as Authorization: DPoP with a new DPoP proof, or as a plain Bearer token: /lws, /files and many /base routes, such as /base/search, take it with no proof; the routes that sign in, trade tokens, register an app or run the AI chat do not. A DPoP proof is a short signed note your app makes for one request, naming its method and address (RFC 9449).

  2. Read the next page with cursor.

    While complete is false, send the same search again with cursor set to next from the answer. Stop when complete is true; next is then null.

    More about this

    total says how many match, with its kind: exact is a count, and atLeast means at least that many. By default the platform counts up to 200 matches and says atLeast beyond that; count=exact asks for the whole count, and count=none for none. count, beside total, is there only when the count is exact. The header x-base-total-kind says the same kind, or none. A page asked with cursor has no total. The cursor is opaque text: send it as it came. Each record found is one you may read; a search never shows that a record you may not read exists.

  3. Get whole records with GET /base/page.

    To have the records themselves, send the same words to the vault's own host:
    GET https://<name>.gilb.com/base/page?q=<words>

    More about this

    The answer holds total and objects, the first 20 matching records in full, with one @context for them all. It takes q, facet and count, but no vault and no cursor, so it gives only the first page; for more, page with GET /base/search and read each address. Only a token with a DPoP proof is taken here: a plain Bearer token is treated as coming from no one, so only what anyone may read comes back.

  4. Find an exact value with GET /base/find-by-attribute.

    Send attr, a fact name such as a:title, and value, the value the fact must hold exactly:
    GET https://id.gilb.com/base/find-by-attribute?attr=<fact name>&value=<value>

    More about this

    It looks in all the vaults you may read at once, and answers count, every match, and ids, 20 by default; limit takes up to 200, and offset pages on. lifecycle=ended or all also finds deleted records. A value that starts with { or [ is read as JSON, so a link is {@id:<address>}; any other value is read as text. Only a token with a DPoP proof is taken: no token, or a plain Bearer token, answers 401 "This authenticated read surface requires a valid credential (absent or unparseable credential presented)".

  5. Find by place with GET /base/spatial.

    Send op=dwithin, a point as geom and a radius in metres:
    GET https://id.gilb.com/base/spatial?op=dwithin&geom=SRID=4326;POINT(<longitude> <latitude>)&radius=<metres>

    More about this

    Only records that hold a c_geometry fact, their shape as a geometry literal, can be found. op=distance sorts by distance and gives each hit its distance; op=within finds records inside an area given as a POLYGON, and op=intersects those that touch it. The answer is count, every match, and hits, at most 20, with no next page. It looks in every vault and keeps what you may read; it takes no vault. Only a token with a DPoP proof counts: with none, or with a plain Bearer token, only what anyone may read is found. dwithin or distance without a radius answers 400 op=dwithin requires a radius, with the op named.

Deeper

Also asked:

How do I search by text, by a field's value, or by place? Search words with GET /base/search, naming the vault; find a field's exact value with GET /base/find-by-attribute; find by place with GET /base/spatial, as the steps show.

A search that is written wrong is refused with 400, not answered empty. No q answers querystring must have required property 'q'. The option is vault, not pod: an option the search does not know answers 400 querystring must NOT have additional properties. A count other than bounded, exact or none answers querystring/count must be equal to one of the allowed values; a type written as t:Name or as a full address answers type_token_unresolved; a cursor the search did not give answers cursor_malformed. A Host the platform does not serve answers 404.

facet=type adds a count of matches per type to a search. lifecycle=ended or all also finds deleted records. An empty answer is not a refusal: the answer on why a result is empty shows what to check.

Find-by-attribute matches the fact name as it was stored: a:title does not find a fact stored under the full address of the term. From the code, not checked on production: a number or true/false fact is not found, because the value is read as text.

Some of these answers are in the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Errors, https://appbuilder.gilb.com/base/e/06gkzpwxmnxf90zcc3mzc757xg; it has no chapter on search yet. It can be read with no sign-in, as data for programs and AIs rather than as a web page.

Source: GilbPlatform 498d29a0 (live at https://id.gilb.com/version, read 2026-11-11): src/routes/search.ts:43-122 (schema: q required, facet, as, lifecycle live|ended|all, vault, match text|prefix, prefer, count bounded|exact|none, cursor, type repeatable; additionalProperties false), :155-186 (searchTargetVault: own vault on the canonical host), :187-238 (opaque cursor, 400 cursor_malformed), :255-371 (bearerFloorSurfacePrincipal; vault= wins, else the routed host; nonDisclosureHostReject; requestedTypeNames), :372-470 (complete and next from one source; x-base-total-kind; prefix adds hits with labels; ids only); src/read/search.ts:48 (SEARCH_PAGE_SIZE 20), :167-211 (exact | atLeast | approximate; TOTAL_MODE_DEFAULT bounded; TOTAL_BOUND_WINDOW 200), :280-299 (total null for none or a cursored bounded page; count only when exact); src/read/search-authorized.ts:100-104 (text = whole token, prefix = token prefix), :515-540 (labels); src/routes/page.ts:39-55 (schema q, facet, as, count; no vault, no cursor), :73-136 (authenticatedPrincipal; routed host; total and objects, one @context); src/routes/attribute-find.ts:43-75 (schema attr, value, lifecycle, limit, offset), :77-91 (parseAttrValue: { or [ as JSON, else text), :106-160 (authenticatedPrincipal; null -> 401 with the quoted message; unregistered Host 404; deriveQueryScopeVaults; limit default 20, max ATTR_FIND_PAGE_MAX 200; answer count and ids); src/read/attribute-find.ts:62, :497-517 (f.attribute = the given name, exact; count(*) OVER); src/authz/reachable-vaults.ts:394-431 (every vault the principal may read, plus the home vault); src/write/canonical.ts:47-55 (JCS hash: text 7 is not number 7); src/routes/spatial.ts:31-108 (schema op dwithin|within|intersects|distance, geom, radius, threeD; 400 radius must be a non-negative number, op=${op} requires a radius; authenticatedPrincipal; no Host check, no vault); src/read/spatial.ts:10-20 (the four relations; metres in 2D), :70-71 (SPATIAL_PAGE_SIZE 20, count unbounded), :195-250 (candidates hold a current c_geometry fact; authz; distance order); src/spatial-vocab.ts (GEOM_ATTR.geometry c_geometry, EWKT); src/auth/principal.ts:197-230 (authenticatedPrincipal: a DPoP credential, else no one); src/auth/bearer-principal.ts:1-30 (the Bearer floor). count=none total null, header none; q=a total atLeast 200, no count, complete false, next; match=prefix hits with label; facet=type facets [{key,count}]; type=ReferenceDocument exact 57; type=t:Note 400 type_token_unresolved; count=all 400 querystring/count must be equal to one of the allowed values; cursor=bad 400 cursor_malformed; pod=x 400 querystring must NOT have additional properties; no q 400 querystring must have required property 'q'; https://appbuilder.gilb.com/base/page?q=card 200 total exact 167, 20 objects, application/ld+json; page with vault= or cursor= 400 additional properties; GET /base/find-by-attribute with no token 401 with the quoted message; GET /base/spatial op=dwithin with no token 200 {count:0,hits:[]}, without radius 400 op=dwithin requires a radius. Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg, pack GilbPlatformDeveloperGuide, 2026-11-11; read for agreement, not copied) Answer06, Answer07, Answer14, Limit07. read each one at its address.", the pod sentence. GilbVeda t:GeometryLiteral (Suggested; public read https://veda.gilb.com/base/terms?q=Geometry%20Literal, 2026-11-11).

For developers

curl

search.sh

# Search one vault for a word. With no token a search finds only the records anyone may read (checked 2026-11-11).
curl -s "https://id.gilb.com/base/search?q=card&vault=https://appbuilder.gilb.com/base"
# {"total":{"kind":"exact","value":167},"count":167,"ids":["https://appbuilder.gilb.com/base/e/...", ...],
#  "pageSize":20,"complete":false,"next":"<cursor>"}

# The next page: the same search, with cursor set to next from the answer before.
curl -s -G "https://id.gilb.com/base/search" \
  --data-urlencode "q=card" \
  --data-urlencode "vault=https://appbuilder.gilb.com/base" \
  --data-urlencode "cursor=<next from the answer before>"

TypeScript

search-all.ts

// Walk every page of one search and collect the record addresses (ids).
// headersFor gives the Authorization and DPoP headers for one request; a new proof each time.
type SearchPage = {
  total: { kind: "exact" | "atLeast" | "approximate"; value: number } | null;
  count?: number;
  ids: string[];
  pageSize: number;
  complete: boolean;
  next: string | null;
};

export async function searchAll(
  words: string,
  vault: string,
  headersFor: (method: string, url: string) => Promise<Record<string, string>>,
): Promise<string[]> {
  const base = "https://id.gilb.com/base/search";
  const ids: string[] = [];
  let cursor: string | null = null;
  for (;;) {
    const params = new URLSearchParams({ q: words, vault });
    if (cursor !== null) params.set("cursor", cursor);
    const res = await fetch(`${base}?${params}`, { headers: await headersFor("GET", base) });
    if (res.status !== 200) throw new Error(`search answered ${res.status}: ${await res.text()}`);
    const page = (await res.json()) as SearchPage;
    ids.push(...page.ids);
    if (page.complete || page.next === null) return ids;
    cursor = page.next;
  }
}

curl

find-value-and-place.sh

# Find every record you may read whose a:title is exactly "Spring plan". A DPoP token and proof are needed.
curl -s -G "https://id.gilb.com/base/find-by-attribute" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/find-by-attribute>" \
  --data-urlencode "attr=a:title" \
  --data-urlencode "value=Spring plan"
# 200: {"count":<all matches>,"ids":["https://<name>.gilb.com/vault/e/<id>", ...]}

# Find records within 1000 metres of a point (longitude first).
curl -s -G "https://id.gilb.com/base/spatial" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/spatial>" \
  --data-urlencode "op=dwithin" \
  --data-urlencode "geom=SRID=4326;POINT(<longitude> <latitude>)" \
  --data-urlencode "radius=1000"
# 200: {"count":<all matches>,"hits":[{"entity":"https://<name>.gilb.com/vault/e/<id>"}, ...]}

Checked against GilbApp d529620.