GIDs
Refer to any record by one identifier that is unique everywhere.
Syntax
A GID is text in three parts after gid://.
gid://namespace/resource/id
The namespace names the owner, the resource names the kind of record, and the id names the record.
Parameters and arguments
gid://The fixed start
namespaceThe owner of the identifier
resourceThe kind of record. An edge stores it, in lower case, as the end's type
idThe record's own identifier
A GID is plain text, so it is a value like any other: hold it in a variable, put it in a list, compare it, return it. Because the parts are separated by /, the text functions take one apart: TEXTSPLIT at / gives gid:, an empty part, then the namespace, the resource and the id, and INDEX counts from 1. A GID can also be tested as text with STARTS WITH.
Examples
One GID in a variable, split at its slashes and read part by part.
Return type and behaviour
Do I have to create a GID? It depends on whose table the record lives in. In your own tables a GID is never required: you choose how rows are identified. In the platform's tables the engine makes the GID for you when you leave it out.
| Where the record is written | Do you create a GID? | What happens |
|---|---|---|
Your own table (CREATE TABLE) | No | The table has the key you declare. With no key declared it gets an id that the database fills in on every INSERT. No GID is made |
| A platform table written by INSERT | No | The engine mints the GID into the table's identifier column when you leave that column out. __id seeds it |
| A platform table written by a governed statement such as an order | No | The handler makes the GIDs of the rows it creates. For the order itself, the sender names it in the order's id field |
| A record that comes from another system | Only if you want its own id kept | Put the other system's id in __id and the GID ends in it |
Your own tables. CREATE TABLE takes the keys from your fields. Mark one or more fields primary_key and those are the identity: any text, number or mix you like, and HTQLDB never adds a GID. Mark none and HTQLDB adds a text column named id as the key, whose default is a random UUID the database fills in when the INSERT leaves id out. A field of your own named id must then be marked primary_key itself. An Integer field marked auto_increment is a number the database counts for you. Nothing in your own table is built as a gid:// value unless you write one. If you want GIDs there, put them in a text field yourself, or use the key a platform table already has.
Platform tables written by INSERT. A platform table that has a GID identifier column (orderId, customerId, collectionId) gets its GID from the engine at the moment of the INSERT, in four steps.
- The column is named by the table's registry entry. If your record already names that column, your value is kept and nothing is minted.
- The namespace comes from the table's registered rule. A rule of
tenanttakes the account's own name from its tenant identifier. A rule oftenants.platformtakes the platform the account's records come from. Any other rule is a fixed namespace. - The resource is the table's registered kind of record, spelled the way the registry spells it:
Order,Customer,Collection,Supplier. - The id is the next number from the table's own pool when the table has the integer
numIdcolumn, and the same number is stored innumId. A table withoutnumIdtakes a fresh 24 character hexadecimal id instead.
A table whose registry entry names no identifier column gets nothing minted. An edge is minted a different way, from the pair it joins.
__id. Put __id in the record when you already have the id: a number or text such as the Shopify id. It is not a column. It sets the last part of the GID, so __id: 9001 gives gid://<namespace>/Collection/9001. If you pass a whole GID as __id, only its last segment is kept, and the namespace and resource still come from the table. A fresh id never uses the pool, so numId is left to the table's own default.
Governed writes. Orders, journals, refunds, returns and the other tables the platform keeps by rules are not written by an account's own INSERT: the engine refuses it with HTQL-3010, and only platform workers and the governed statements write them. Those statements build rows through handlers, and the handlers mint every GID themselves, in the table's namespace and resource, so you never supply one. The exception is the record you are telling the platform about: the sender names an order in its order_id, which is the id the source system already gave it, and the rows the platform derives from it take their GIDs from it.
What comes back. INSERT answers the ids of every row it wrote in info.insertedIds, one record per row, in the order written. gid is the row's GID; a table of your own that has none answers key, its primary key (a composite key as a JSON list). id is the row's number from the id pool, given as text because it is larger than a JSON number holds exactly. replicaId is where the row is placed: its tenant, its guild or its member. Each appears when the table has it, and each is the value as stored, so an id the database drew is reported as it was drawn. An UPSERT answers info.insertedIds for the rows it inserted and info.updatedIds for the rows it updated, in the same form. A table with none of these answers neither.
"info": {
"insertedIds": [
{
"gid": "gid://…/Collection/…",
"id": "…",
"replicaId": "gid://…/Tenant/…"
}
]
}
An edge between two records stores each end as a GID. The third part, the resource, is stored as the end's type.
A document read by GID finds its table from the resource, by its plural (order reads orders), and its identifier column as the resource followed by _id. See Document retrieval.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-6012 | An edge end is not a GID in the form above, or names a record that does not exist | Write gid://namespace/resource/id, and check the record exists |
Limitations
- An edge's ends must be written as GIDs in this form, or the edge is refused.
- For the platform's own record types (for example
order,customer,product,supplier), an edge's end must exist. Any other resource name is accepted as an opaque identifier. - A document key must have all three parts.
gid://acme/orderis refused.