MyJackfruit

Help
Browse topics · For developers

For developers

← For developers

How do I import and export in bulk?

Short answer

Write an import mapping, send the file with it to POST /base/import, then export the imported records with GET /base/export.

Before you start

Your app holds a person's sign-in token and the key it is bound to. The file is an xlsx workbook (a spreadsheet), JSON-LD (JSON with a fixed set of names) or N-Triples (one statement a line), smaller than about 750 KB. The import takes only a token with a DPoP proof, a short signed note your app makes for one request, naming its method and address (RFC 9449).

Words used here (6)
import mapping
An import mapping is a record whose rules say how the sheets, columns or statements of a file become records and facts in a vault.
record
A record is one piece of data with its own address, such as a person, a place, a thing or a note.
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.
record's address
A record's address is the web address that names one record for good: it never changes and is never given to another record.
agent
An agent is your AI following one written procedure, its standing instructions, for one kind of work.
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.
Steps
  1. Write an import mapping record.

    Create a record of type t:ImportMapping whose facts say how the file becomes records: a:sourceForm, xlsx or jsonld, and the rules. The answer on creating a record in a vault shows how to create one.

    More about this

    For a workbook, a:sheetRules is a list of {sheet, type, idColumn}: the type each row of that sheet becomes, and the column, by its heading, whose cell names the row. a:columnRules is a list of {sheet, column, attribute, coerce}: which fact each column fills. coerce is string, number, boolean or id; id makes the cell a link. For JSON-LD or N-Triples, a:predicateRules is a list of {predicate, attribute, coerce}, and rdf:type gives the type. A sheet, column or predicate with no rule, and a row with no id, is left out. The platform reads the rules at each import, so changing them changes the next one. a:sheetRules, a:columnRules and a:predicateRules are not yet terms in GilbVeda, the shared list of terms.

  2. Send the file to POST /base/import.

    Send source, the file in base64, which writes its bytes as plain text, mapping, the mapping record's address, and agent, the address that stands for who imports, kept with every fact:
    POST https://id.gilb.com/base/import

    More about this

    The answer is 201 with entities, each record with changed true or false, constructsIn, the cells or statements read, and constructsMapped, those that became facts. A row of a workbook becomes the record https://<the platform's host>/base/e/<its id>, where its id is the text of its id cell with each character other than a letter, a digit, a dot, an underscore, a tilde or a hyphen made a hyphen, so sending the file again changes the same records; a statement's subject is its record's address. Each record goes to the vault its address names, and every one is checked before the first write: one you may not write leaves the whole file unwritten, with 403. Each record keeps a:importSource, where in the file each fact came from.

  3. Count a vault's records by type.

    Ask the vault's own host for its type census, with the vault's address put through encodeURIComponent:
    GET https://<name>.gilb.com/lws/vault/<encoded vault id>/types

    More about this

    The answer lists types, each typeUri with a count of the records of that type you may read, and no records. A count of 1000 or more is given as 1000, and totalItemsKind says atLeast; count=exact asks for every count in full. excludedTypes names the types left out of the list, with their counts. It takes a plain Bearer token, sent with no proof, as well as DPoP. With no token, or on a vault you may not read, it answers 403 vault target denied.

  4. Export imported records with GET /base/export.

    Name each record with entity, as many times as you need, and choose form, jsonld or xlsx:
    GET https://id.gilb.com/base/export?entity=<record address>&form=jsonld

    More about this

    It rebuilds the file the records came from, from their a:importSource: form=jsonld gives N-Triples text, one statement a line, and form=xlsx gives the sheets' cells as XML text, not a workbook file. A record that was not imported, or that you may not read, gives nothing, and no error says so. With no entity it answers 400 at least one ?entity= is required. Only a token with a DPoP proof is taken; with a plain Bearer token the answer is empty.

Deeper

Also asked:

Can I write several records in one request, all or nothing? No: each create, PUT, PATCH or DELETE writes one record, and no request writes several records as one all-or-nothing change. POST /base/import writes a file's records one at a time, so a failure part way keeps those already written.

How do I import a file of records, or export them all? Import with a mapping record and POST /base/import; GET /base/export gives back only imported records. To take every record out, list the vault page by page with include=body, or take a copy of the whole vault with its files.

From the code, not checked on production: the platform takes an import only from someone who may write its own home vault, https://<the platform's host>/base, the vault every workbook row is written to. Anyone else gets 403 WriteForbiddenError, is not authorized to import, before the file is read. A mapping address with no record behind it answers 500.

A request body is at most about 1 MiB, so the file, in base64, must fit in it; a larger one answers 413 Request body is too large. A JSON-LD file may name only the platform's own @context; the platform fetches no other. A body with a field other than source, mapping and agent, or without one of those three, answers 400.

To take every record of a vault out, not only imported ones, read the listing a page at a time with include=body, which gives each record in full; the answer on listing records and what changed since shows how. To copy a whole vault with its files, see the answer on creating a vault, listing vaults and exporting one by API.

The listing is in the Developer Guide, GilbPlatform's guide for people who build apps on it, in its chapter Dev.Guide.Reading, https://appbuilder.gilb.com/base/e/06gkzpwp39x2q3dxgj4ytavpvg, and the copy of a vault in its chapter Dev.Guide.Files, https://appbuilder.gilb.com/base/e/06gkzpww3sseh5eskg4h42ts5g; it has no chapter on import 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/import.ts:19-31 (body source, mapping, agent required; additionalProperties false), :43-61 (POST /base/import; writeRequirer; 201), :63-92 (GET /base/export; entity repeatable; 400 at least one ?entity= is required; form xlsx else jsonld; authenticatedPrincipal + authorizeReadIds: only readable records; text/plain); src/import/vocab.ts:15-75 (a:sourceForm, a:columnRules, a:sheetRules, a:predicateRules with their shapes and coerce values; a:importSource; t:ImportMapping; importedEntityUri = https://<ownerHost>/base/e/<id tail>); src/import/import.ts:101-108 (ImportResult), :119-136 (loadMappingSpec; plain Error Import mapping not found -> 500 by src/server/app.ts:244-270), :170-268 (sheet, column, predicate with no rule and a row with no id skipped; rdf:type; coerce id -> link), :283-358 (write gate on https://<ownerHost>/base before parse, WriteForbiddenError is not authorized to import; vaultForNamedCreate for every subject before the first write; a:importSource stamped), :375-420 (export from a:importSource: N-Triples, xlsx sheet XML); src/import/parse.ts:1-40, :89-102, :104-130, :360-385 (xlsx by ZIP, JSON-LD to N-Quads, N-Triples line-wise; no remote @context); src/auth/principal.ts:269-280 (writeRequirer = authenticatedPrincipal: DPoP only); src/write/errors.ts:30-36 (WriteForbiddenError 403); src/routes/ai-chat.ts:77 (Fastify bodyLimit 1 MiB; no bodyLimit set in src); src/lws/routes.ts:624-627 (GET /lws/types 400, vault required), :729-746 (GET /lws/vault/:vaultId/types; vaultTarget, the /lws Bearer floor); src/lws/held-types.ts:1-63 (row-less per-viewer census; types[{typeUri,count}], totalItemsKind exact|atLeast, excludedTypes), :93-95 (bound 1000), :124-130 (count=exact). Public read, no token, 2026-11-11: https://appbuilder.gilb.com/lws/vault/https%3A%2F%2Fappbuilder.gilb.com%2Fbase/types 403 "vault target denied: the principal holds no read reach on vault https://appbuilder.gilb.com/base". GilbVeda public reads 2026-11-11: t:ImportMapping (Suggested), a:sourceForm 200 (inline-literal:enum), a:importSource 200; a:columnRules, a:sheetRules, a:predicateRules 404. Dev.Guide.Errors (A 06gkzpwxmnxf90zcc3mzc757xg, 2026-11-11) Answer42 (413 Request body is too large); Dev.Guide.Reading (A 06gkzpwp39x2q3dxgj4ytavpvg, 2026-11-11) List, Walk; Dev.Guide.Files (A 06gkzpww3sseh5eskg4h42ts5g). All Standards; read for agreement, not copied. GilbPlatform 0fc5a548 (live at https://id.gilb.com/version, read 2026-11-14): src/import/import.ts:323-353 (one ingestState per record, each its own write); src/routes/write.ts:109-145 (POST /base/ingest: one record); Dev.Guide.Writing (A 06gkzpwmgnzph1fb6jp7gf87c0, 2026-11-14): each create, PUT, PATCH and DELETE names one record.

For developers

TypeScript

import-file.ts

// Send a file to POST /base/import with the address of an import mapping record.
// headersFor gives the Authorization and DPoP headers for one request; a new proof each time.
import { readFile } from "node:fs/promises";

type ImportResult = {
  entities: { entity: string; changed: boolean }[];
  constructsIn: number;
  constructsMapped: number;
};

export async function importFile(
  path: string,
  mapping: string,
  agent: string,
  headersFor: (method: string, url: string) => Promise<Record<string, string>>,
): Promise<ImportResult> {
  const url = "https://id.gilb.com/base/import";
  const source = (await readFile(path)).toString("base64");
  const res = await fetch(url, {
    method: "POST",
    headers: { ...(await headersFor("POST", url)), "Content-Type": "application/json" },
    body: JSON.stringify({ source, mapping, agent }),
  });
  if (res.status !== 201) throw new Error(`import answered ${res.status}: ${await res.text()}`);
  return (await res.json()) as ImportResult;
}

curl

census-and-export.sh

# Count the records of each type in a vault. Bearer or DPoP; here DPoP with a new proof.
VAULT="<the vault's address, put through encodeURIComponent>"
curl -s "https://<name>.gilb.com/lws/vault/$VAULT/types" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://<name>.gilb.com/lws/vault/$VAULT/types>"
# 200: {"types":[{"typeUri":"t:Note","count":12}, ...],"totalItemsKind":"exact", ...}

# Export two imported records in their source form, as N-Triples.
curl -s -G "https://id.gilb.com/base/export" \
  -H "Authorization: DPoP <token>" \
  -H "DPoP: <a new proof for GET https://id.gilb.com/base/export>" \
  --data-urlencode "entity=<record address>" \
  --data-urlencode "entity=<another record address>" \
  --data-urlencode "form=jsonld"

Checked against GilbApp d529620.