Skip to main content

System Collections

When a new ledger is created, the first transaction, issued automatically by Fluree, initializes system collections and predicates.

These system collections govern various ledger behaviors, such as schema, user rules, smart functions. Each of these system collections and their predicates is discussed in its respective section. The below list compiles all of the built-in collections in one place, and you can follow the link to any particular section for more information.

All System Collections

All ledgers are created with the following collections.

CollectionDescription
_collectionSchema collections list
_predicateSchema predicate definition
_tagTags
_fnledger functions
_userledger users
_authAuth records. Every db interaction is performed by an auth record which governs permissions.
_roleRoles group multiple permission rules to an assignable category, like 'employee', 'customer'.
_rulePermission rules
_blockBlock metadata
_txledger transactions
_settingledger settings

_collection

PredicateTypeDescription
_collection/namestring(required) The name of the collection. Collection names are aliases to an underlying collection integer identifier, and therefore it is possible to change collection alias to a different collection ID. Note that if you intend to use GraphQL tools, predicate names must conform to /[_A-Za-z][_0-9A-Za-z]*/. If you do not conform to this standard, queries issued to the /graphql endpoint will still work, but many GraphQL tools will not.
_collection/docstring(optional) Optional docstring describing this collection.
_collection/spec[ref](optional) A multi-cardinality list of refs, which reference entities in the _fn collection. These specs restricts what is allowed in this collection. To learn more, visit the Collection Spec and Predicate Spec sections in the Guides.
_collection/specDocstring(optional) Optional docstring to describe the specs. Is thrown when any spec fails.
_collection/versionstring(optional) For your optional use, if a collection's spec or intended predicates change over time this version number can be used to determine which schema version a particular application may be using.

_predicate

PredicateTypeDescription
_predicate/namestring(required) Actual predicate name. Must be namespaced, and convention is to namespace it using the collection name you intend it to be used within. Technically any predicate can be placed on any subject, but using a spec can restrict this behavior. Note that if you intend to use GraphQL tools, predicate names must conform to /[_A-Za-z][_0-9A-Za-z]*/. If you do not conform to this standard, queries issued to the /graphql endpoint will still work, but many GraphQL tools will not.
_predicate/docstring(optional) Doc string for this predicate describing its intention. This description is also used for GraphQL automated schema generation.
_predicate/typetag(required) Data type of this predicate such as string, integer, or a reference (join) to another subject - ref. See table below for valid data types.
_predicate/uniqueboolean(optional) True if this predicate acts as a primary key. Unique predicates can be used for idsubject (as the _id value in a transaction or query). (Default false.)
_predicate/multiboolean(optional) If this is a multi-cardinality predicate (holds multiple values), set to true. (Default false.)
_predicate/indexboolean(optional) True if an index should be created on this predicate. A predicate marked as unique automatically will generate an index and will ignore the value specified here. (Default false.)
_predicate/upsertboolean(optional) Only applicable to predicates marked as unique. If a new subject transaction using this predicate resolves to an existing subject, update that subject. By default the transaction will throw an exception if a conflict with a unique predicate exists.
_predicate/noHistoryboolean(optional) By default, all history is kept. If you wish to turn this off for a certain subject, set this flag to true. Queries, regardless of time travel, will always show the current value.
_predicate/componentboolean(optional) For type 'ref' predicates only. Mark true if this predicate refers to an subject which only exists as part of the parent subject. If true, and the parent subject is deleted, the subject referenced by this predicate will also be deleted automatically. (Default false.)
_predicate/spec[ref](optional) A multi-cardinality list of refs, which reference entities in the _fn collection. These specs restricts what is allowed in this _predicate. To learn more, visit the Collection and Predicate Specs section in the Fluree Guide.
_predicate/specDocstring(optional) Optional docstring to describe the specs. Is thrown when any spec fails.
_predicate/deprecatedboolean(Not in production yet, optional) True if this v is deprecated. Reads and writes are still allowed, but might give warnings in the API.
_predicate/txSpec[ref](optional) A multi-cardinality list of refs, which reference entities in the _fn collection. This predicate allows you to set specifications for all of the flakes pertaining to a certain predicate. To learn more, visit the Predicate Tx Specs section in the Fluree Guides.
_predicate/txSpecDocstring(optional) Optional docstring to describe the txSpecs. Is thrown when any txSpec fails.
_predicate/restrictCollectionstring(optional) Only applicable to predicates of ref (reference) types. It will restrict references to only be allowed from the specified collection.
_predicate/restrictTagboolean(optional) Only applicable to predicates of type tag. If true, a tag, which corresponds to this predicate object, must exist before adding predicate-object pair.
_predicate/encryptedboolean(Not in production yet, optional) Expects the value to come in as an encrypted string. Type checking will be disabled, and ledger functions won't be permitted on this value.
_predicate/fullTextboolean(optional) If true, full text search enabled on this ledger. By default, the language for a Fluree ledger is set to English. You can change the default language in _setting collection.

_predicate Types

Supported predicate types are as follows:

TypeDescription
stringUnicode string (_type/string)
refReference (join) to another collection (_type/ref)
tagA special tag predicate. Tags are auto-generated, and create auto-resolving referred entities. Ideal for use as enum values. Also they allow you to find all entities that use a specific tag. (_type/tag)
int32 bit signed integer (_type/int)
long64 bit signed integer (_type/long)
bigintArbitrary sized integer (more than 64 bits) (_type/bigint)
float32 bit IEEE double precision floating point (_type/float)
double64 bit IEEE double precision floating point (_type/double)
bigdecIEEE double precision floating point of arbitrary size (more than 64 bits) (_type/bigdec)
instantMillisecond precision timestamp from unix epoch. Uses 64 bits. (_type/instant)
booleantrue/false (_type/boolean)
uriURI formatted string (_type/uri)
uuidA UUID value. (_type/uuid)
bytesMust input bytes as a lowercase, hex-encoded string (_type/bytes)
jsonArbitrary JSON data. The JSON is automatically encoded/decoded (UTF-8) with queries and transactions, and JSON structure can be validated with a spec. (_type/json)
geojsonGeospatial JSON data. GeoJSON is an open standard format designed to represent simple geographical features. (_type/geojson)

_tag

PredicateTypeDescription
idstringNamespaced tag id
docstringOptional docstring for tag

_fn

PredicateTypeDescription
namestringFunction name
params(multi) stringList of parameters this function supports.
codestringActual ledger code
docstringA docstring for this function.
languagestringProgramming language used (not yet implemented, currently only Clojure supported)
specJSON(not yet implemented) Optional spec for parameters. Spec should be structured as a map, parameter names are keys and the respective spec is the value.

_user

PredicateTypeDescription
_user/usernamestring(optional) A unique username for this user.
_user/auth[ref](optional) Reference to auth entities available for this user to authenticate. Note if no auth entities exist, the user will be unable to authenticate.
_user/roles[ref](optional) References to the default roles that apply to this user. If roles are specified via the _auth subject the user is authenticated as, those roles will always override (replace) any role specified here.

_auth

PredicateTypeDescription
_auth/idstring(optional) Globally unique id for this auth record.
_auth/docstring(optional) A docstring for this auth record.
_auth/keystring(optional) A unique lookup key for this auth record.
_auth/typetag(optional) The type of authorization this is. Current type tags supported are: password.
_auth/secretstring(optional) The hashed secret. When using this as a password _auth/type, it is the one-way encrypted password. This predicate is not used anywhere in the ledger, but you can create an application using logins and passwords with the help of this predicate.
_auth/hashTypetag(optional) The type of hashing algorithm used on the _auth/secret.
_auth/resetTokenstring(optional) If the user is currently trying to reset a password/secret, an indexed reset token can be stored here allowing quick access to the specific auth record that is being reset. This predicate is not used anywhere in the ledger, but you can create an application using logins and passwords with the help of this predicate.
_auth/roles[ref](optional) Multi-cardinality reference to roles to use if authenticated via this auth record. If not provided, this _auth record will not be able to view or change anything in the ledger.
_auth/authority[ref](optional) Authorities for this auth record. References another _auth record. Any auth records referenced in _auth/authority can sign a transaction in place of this auth record. To use an authority, you must sign your transaction using the authority's auth record. See more about signing transactions and authorities in the Signed Transactions section of the Guides.
_auth/fuellongFuel this auth record has. Fuel is used to meter usage in the hosted version of Fluree, but an application can use this predicate to meter fuel usage in the downloadable version as well.

_role

PredicateTypeDescription
_role/idstring(optional) A unique identifier for this role.
_role/docstring(optional) A docstring for this role.
_role/rules[ref](required) References to rule entities that this role aggregates.

_rule

PredicateTypeDescription
_rule/idstring(optional) A unique identifier for this rule.
_rule/docstring(optional) A docstring for this rule.
_rule/collectionstring(required) The collection name this rule applies to. In addition to a collection name, the special glob character * can be used to indicate all collections (wildcard).
_rule/collectionDefaultbooleanIndicates if this rule is a default rule for the specified collection. Use either this or _rule/predicates on a rule, but not both. Default rules are only executed if a more specific rule does not apply, and can be thought of as a catch-all.
_rule/predicates[string](optional) A multi-cardinality list of predicates this rule applies to. The special glob character * can be used to indicate all predicates (wildcard).
_rule/fns[ref](required) Multi-cardinality reference to _fn subject. The actual function is stored in the _fn/code predicate. _fn/code can be true, false, or a ledger function expression. Built-in functions and variables are listed in ledger Functions. true indicates the user always has access to this collection + predicate combination. false indicates the user is always denied access. Functions will return a truthy or false value that has the same meanings.
_rule/ops[tag](required) Multi-cardinality tag of action(s) this rule applies to. Current tags supported are query for query/read access, transact for transact/write access, and all for all operations.
_rule/errorMessagestring(optional) If this rule prevents a transaction from executing, this optional error message can be returned to the client instead of the default error message (which is intentionally generic to limit insights into the ledger configuration).

_block

KeyDescription
numberBlock number for this block.
hashHash for current block. Not included in block hash (can't include itself!).
prevHashPrevious block's hash
transactionsReference to transactions included in this block (_tx).
transactorsReference to transactor auth identities that signed this block. Not included in block hash.
instantInstant this block was created, per the transactor.
sigsList of transactor signatures that signed this block (signature of _block/hash). Not included in block hash.

_tx

KeyDescription
tempidsTempid JSON map for this transaction.
sigSignature of original JSON transaction command.
txOriginal JSON transaction command.
docOptional docstring for the transaction.
altIdAlternative Unique ID for the transaction that the user can supply. Transaction will throw if not unique.
nonceA nonce that helps ensure identical transactions have unique txids, and also can be used for logic within smart functions (not yet implemented). Note this nonce does not enforce uniqueness, use _tx/altId if uniqueness must be enforced.
authorityIf this transaction utilized an authority, reference to it.
authReference to the auth id for this transaction.

_setting

KeyDescription
txMaxMaximum transaction size in bytes. Will default to the network db's value if not present.
anonymousReference to auth identity to use for anonymous requests to this db.
consensusConsensus type for this db. Currently only 'Raft' supported.
ledgersReference to auth identities that are allowed to act as ledgers for this ledger.
docOptional docstring for the db.