Skip to content

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:

python
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:

python
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 ​

python
# 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 callerThe list holds
uploaded the referenced record, or was granted private access to itevery record that references it, in every access group, private ones included
anyone elsereferencing 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.

python
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_limitHow many records may reference this one. None (default) is no limit, 0 allows none.
prevent_multiple_referencingTrue: each user may reference it only once. Good for votes.
can_remove_referencing_recordsTrue: the uploader may delete records that reference it, and deleting it deletes them too. Good for a post owner removing comments.
only_granted_can_referenceTrue: only users with private access may reference it.
allow_granted_to_grant_othersTrue: users with private access may grant it to others.
referencing_index_restrictionsA 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:

python
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.

skapi-py 2.4.0