Skip to main content

Basic Transaction

Fluree allows you to specify transactions using FlureeQL, a JSON array/vector syntax which contains subject maps to create, update, upsert or delete. The maximum transaction size is 10 MB.

Transactions can also be done with GraphQL, for more information on GraphQL transactions, reference the GraphQL Transactions section.

Transact Keys

Each map requires an _id as specified below along with key/value pairs containing the predicates and values you wish to modify. An _action key is always included, but typically inferred and thus optional for most operations.

KeyTypeDescription
_idsubject idAny subject id value which can include the numeric assigned permanent _id for a subject, any predicate marked as unique as a two-tuple, i.e. ["_user/username", "jdoe"], or a temporary id (for new entities).
_actionstringOptional (if it can be inferred). One of: add, update, upsert or delete. When using a temporary id, add is always inferred. When using an existing subject id, update is always inferred. upsert is inferred for new entities with a tempid if they include a predicate that was marked as upsert.

Temporary Ids

Every transaction item must have an _id predicate to refer to the subject we are attempting to create/update. A tempid can simply be the collection name, i.e. _user.

FlureeQL example:

[
{
"_id": "_user",
"username": "eWasswa"
}
]

However, if you would like to reference that tempid somewhere else in your transaction, it is necessary to create a unique tempid. To make a unique tempid, just append the collection with any non-valid collection character (anything other than a-z, A-Z, 0-9, _) followed by anything else. For example, _user$lEliasz or _user#1.

FlureeQL example:

[
{
"_id": "_user$lEliasz",
"username": "lEliasz",
"auth": ["_auth$temp"]
},
{
"_id": "person",
"handle": "lEliasz",
"fullName": "Louis Eliasz",
"user": "_user$lEliasz"
},
{
"_id": "_auth$temp",
"id": "tempAuthRecord"
}
]

Adding Custom Metadata

When issuing a transaction, you can include your own metadata. For example, if you want to include a _tx/note, you can issue the below transaction to create the relevant predicate (field):

[
{
"_id": "_predicate",
"name": "_tx/note",
"type": "string"
}
]

And, then, whenever you issue a transaction, you are able to include a _tx/note.

[
{
"_id": "_user",
"username": "abc"
},
{
"_id": "_tx",
"note": "hey there"
}
]

Fuel

Fuel is used to meter usage. Every query and transaction accumulates a certain amount of "fuel." The amount of fuel used is returned in the query or transaction results. Currently, fuel is primarily used as supplemental information.