Skip to main content

Collections

A collection is analogous to a relational database table. Every time you want a new type of item in your ledger, you would create a new collection. For example, collections in your ledger might be person, company, and city.

Collections are recorded in the ledger in the same way as any other type of data. The syntax for updating the _collection collection or _collection predicates is the same as updating any other type of information. Furthermore, if you wanted to add additional predicates to the _collection collection, you can.

_collection Predicates​

Below are the built-in predicates for the _collection collection. As mentioned above, you can add additional predicates if you wish.

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.
_collection/docstring(optional) Optional docstring describing this collection.
_collection/spec[ref](optional) A multi-cardinality list of reference to the _fn collection. These specs restrict what is allowed in this collection. To see how to write a function, see the function section.
_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.

Creating Collections​

Creating collections is done in the same way as creating any other type of subject in the ledger. In the below example, we create four new collections: person, chat, comment, and artist. We strongly discourage adding smart functions to your _collection/spec when you initially create a collection. If you would like a _collection/spec, visit the functions section to understand how to incorporate smart functions into your schema.

[
  {
    "_id": "_collection",
    "name": "person",
    "doc": "A collection to hold all the people in our ledger",
    "version": 1
  },
  {
    "_id": "_collection",
    "name": "chat",
    "doc": "A collection to hold all the chats in our ledger",
    "version": 1
  },
  {
    "_id": "_collection",
    "name": "comment",
    "doc": "A collection to hold all the comments in our ledger",
    "version": 1
  },
  {
    "_id": "_collection",
    "name": "artist",
    "doc": "A collection to hold all the artists in our ledger",
    "version": 1
  }
]

Adding a Predicate to _collection​

_collection is a built-in ledger collection with built-in predicates. This does not mean, for instance, that you cannot add predicates. For example, you may want to add a _collection/longDescription predicate, where you store a longer version of _collection/doc.

You can do this by adding a new predicate:

[
  {
    "_id": "_predicate",
    "name": "_collection/longDescription",
    "type": "string"
  }
]

After you add this predicate, you can update any existing collections to include a long description:

[
  {
    "_id": ["_collection/name", "person"],
    "longDescription": "I have a lot to say about this collection, so this is a longer description about the person collection"
  }
]
  curl \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer $FLUREE_TOKEN" \
   -d '[{
    "_id": ["_collection/name", "person"],
    "longDescription": "I have a lot to say about this collection, so this is a longer description about the person collection"
}]' \
   [HOST]/api/db/transact

And you can create new collections with a _collection/longDescription:

[
  {
    "_id": "_collection",
    "name": "animal",
    "longDescription": "I have a lot to say about this collection, so this is a longer description about the animal collection"
  }
]

Updating a Predicate in _collection​

Although you can change built-in collection predicates, we do not recommend doing so, as your changes may break certain aspects of schema validation.

One commonly-requested safe change, however, is to allow _collection/name to be upsertable. By default, _collection/name does not allow upsert, meaning if you try to create a new collection with the name of already existing collection, an error will be thrown. You can change this, however, by editing the predicate, _collection/name. To see all the existing predicates for the _collection/name predicate, you can issue the following query:

{
  "select": ["*"],
  "from": ["_predicate/name", "_collection/name"]
}

The default features of _collection name are:

{
  "_predicate/name": "_collection/name",
  "_predicate/doc": "Schema collection name",
  "_predicate/type": "string",
  "_predicate/unique": true,
  "_id": 40 // id depends on Fluree version
}

As we can see, there is no upsert key in the predicate, so by default upsert is false. To change this, we can issue:

[
  {
    "_id": ["_predicate/name", "_collection/name"],
    "upsert": true
  }
]

Now, we allow upsert for the _collection/name predicate.