References
A record can reference one other record. Comments on a post, votes on a poll, items in an order: the child records reference the parent, and you fetch them by the parent's ID.
Referencing a record
Put the parent's record ID or unique ID in reference:
from skapi import Skapi, SkapiError
skapi = Skapi("<Project ID>")
post = skapi.post_record(
{"text": "What do you think of this?"},
{"table": {"name": "posts", "access_group": "public"}, "unique_id": "post:1"},
)
skapi.post_record(
{"text": "I like it"},
{"table": {"name": "comments", "access_group": "public"},
"reference": post["record_id"]}, # or "post:1"
)reference also takes a dict, {"record_id": ...} or {"unique_id": ...}. The saved record has the parent's record ID in record["reference"], and the parent's referenced_count goes up by one.
To remove a reference, update the record with "reference": None:
skapi.post_record(config={"record_id": "<comment id>", "reference": None})A user cannot reference a record in a higher access group than their own, or a private record, unless the uploader granted them private access to it.
Fetching references
# the comments of a post, in one table and one access group
skapi.get_records({
"table": {"name": "comments", "access_group": "public"},
"reference": "post:1",
})
# every record that references the post, in every table (signed in only)
skapi.get_records({"reference": "post:1"})Without table, what comes back depends on who asks:
| The caller | The list holds |
|---|---|
| uploaded the referenced record, or was granted private access to it | every record that references it, in every access group, private ones included |
| anyone else | referencing records in access groups up to their own; no private records |
Signed-out callers always need table. One call without table replaces one call per table, so prefer it to looping over tables.
A user ID in reference returns that user's records: your own in every table, or another user's in the table you name.
skapi.get_records({
"table": {"name": "comments", "access_group": "public"},
"reference": "<user id>",
})Sorting by the number of references, for example the posts with the most comments, uses the $referenced_count index.
Reference rules
source in the config of the parent sets rules for the records that reference it:
| key | |
|---|---|
referencing_limit | How many records may reference this one. None (default) is no limit, 0 allows none. |
prevent_multiple_referencing | True: each user may reference it only once. Good for votes. |
can_remove_referencing_records | True: the uploader may delete records that reference it, and deleting it deletes them too. Good for a post owner removing comments. |
only_granted_can_reference | True: only users with private access may reference it. |
allow_granted_to_grant_others | True: users with private access may grant it to others. |
referencing_index_restrictions | A list of index rules the referencing records must meet, see below. |
Index restrictions
Each rule is a dict with name (required), and optionally value and condition. A referencing record must have an index with that name, of the same type as value, that meets the condition ("=" when left out). The conditions are "=", "!=", ">", ">=", "<", "<=" and the word forms eq, ne, gt, gte, lt, lte.
A review board where 10 people can each rate once, below 5:
skapi.post_record(
{"title": "Rate the album Getz/Gilberto"},
{
"table": {"name": "reviews", "access_group": "public"},
"unique_id": "reviews:getz-gilberto",
"source": {
"referencing_limit": 10,
"prevent_multiple_referencing": True,
"referencing_index_restrictions": [
{"name": "rating", "value": 5, "condition": "<"},
],
},
},
)
skapi.post_record(
{"comment": "Wonderful"},
{
"table": {"name": "reviews", "access_group": "public"},
"reference": "reviews:getz-gilberto",
"index": {"name": "rating", "value": 4.5},
},
)Use a number for the rating so get_indexes can report the total and average.
referencing_limit must be a number from 0 up, or None. A rule with a range key is refused (INVALID_PARAMETER: Index restriction "range" type should match the type of "value".), so express ranges with condition.
WARNING
A user with private access to a record can read every record that references it, private ones included. If that is not what you want, do not let users post private records that reference other records.
