Collection Spec
A _collection/spec
is set of smart functions that are attached to a particular collection. Any time that collection appears in a transaction, regardless of who issues the transaction, the smart functions attached to the _collection/spec
will execute.
If all of the smart functions return true, the transaction will succeed. If any of the smart functions return false, it will fail.
The examples in this section use the Basic Schema.
Example Uses
- Certain predicates are required.
- If a certain predicate is included, other predicates are required.
The main use for _collection/spec
is to require, or to conditionally require, certain predicates. For example, you might want to require person/fullName
. Any transaction that would leave a person without a full name would be rejected. This includes creating a new person without a full name or deleting a full name from a person.
Example: person/fullName Required
If we want to make person/fullName
required, we need to first create a smart function and then reference that function in the person
collection spec.
It might be tempting to think that, because this smart function pertains to one specific predicate, then we should use a predicate spec. However, we could be creating new people with the following transaction:
[
{
"_id": "person",
"handle": "gWash"
},
{
"_id": "person",
"handle": "johnnyQ"
}
]
The above transaction should not be allowed if we want to require full names, but it would not trigger any smart functions attached to the person/fullName
_predicate/spec
. This is because the fullName
predicate does not appear anywhere in the transaction. Instead, we need to put the smart function on the _collection/spec
for person/fullName
.
Note, in our smart function, we first use our ?sid
to find the person/fullName
. We retrieve the person/fullName
using get
, and then we coerce the result to a boolean (true
or false
), so that any non-nil value will return true
and nil
will return false
.
In the below transaction, we first attach the _fn$fullNameReq
to the person
collection, and write a specDoc
. The specDoc
is the custom error message that will display when this smart function returns false. In the second part of the transaction, we create the relevant smart function, fullNameReq
.
- FlureeQL
- Curl
- GraphQL
- SPARQL
[
{
"_id": ["_collection/name", "person"],
"spec": ["_fn$fullNameReq"],
"specDoc": "A person is required to have a fullName."
},
{
"_id": "_fn$fullNameReq",
"name": "fullNameReq",
"code": "(boolean (get (?s) \"person/fullName\"))"
}
]
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $FLUREE_TOKEN" \
-d '[{
"_id": ["_collection/name", "person"],
"spec": ["_fn$fullNameReq"],
"specDoc": "A person is required to have a fullName."
},
{
"_id": "_fn$fullNameReq",
"name": "fullNameReq",
"code": "(boolean (get (?s) \"person/fullName\"))"
}]' \
[HOST]/api/db/transact
mutation reqFullName ($reqFullNameTx: JSON) {
transact(tx: $reqFullNameTx)
}
{
"reqFullNameTx": "[{\"_id\":[\"_collection/name\",\"person\"],\"spec\":[\"_fn$fullNameReq\"],\"specDoc\":\"A person is required to have a fullName.\"},{\"_id\":\"_fn$fullNameReq\",\"name\":\"fullNameReq\",\"code\":\"(boolean (get (?s) \\\"person/fullName\\\"))\"}]"
}
Transactions not supported in SPARQL
After we add this _collection/spec
, the following transaction should fail:
- FlureeQL
- Curl
- GraphQL
- SPARQL
[
{
"_id": "person",
"handle": "noFullName"
}
]
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $FLUREE_TOKEN" \
-d '[{
"_id": "person",
"handle": "noFullName"
}]' \
[HOST]/api/db/transact
mutation addPersonNoFullName ($addPersonNoFullNameTx: JSON) {
transact(tx: $addPersonNoFullNameTx)
}
{
"addPersonNoFullNameTx": "[{\"_id\":\"person\",\"handle\":\"noFullName\"}]"
}
Transactions not supported in SPARQL