Skip to main content

Social Interactions

NEAR components can natively communicate with the SocialDB smart contract (currently deployed at social.near).

The SocialDB is a contract that stores key-value pairs, and is used mostly to store social-related data, such as posts, likes, or profiles.

tip

Besides user data, the SocialDB contract stores all existing NEAR components.


Social.getโ€‹

Social.get queries a key from the SocialDB contract and returns the data. The key being queried can contain wildcards.

For example:

  • alice.near/profile/** will match the entire profile data of account alice.near.
  • alice.near/profile/* will match all the fields of the profile, but not the nested objects.
  • alice.near/profile/name will match only the name field of the profile.
  • */widget/* will match all the widgets of all the accounts.

Loading...
Parameters
paramrequiredtypedescription
patternsrequiredstring / string[]the path pattern(s)
finalityoptional"final" / numberthe block height or finality
optionsoptionalobjectthe options object.
options object
  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_deleted (optional): whether to return deleted values (as null). Default is false.

The block height or finality can be used to get the data at a specific block height or finality. If the block height or finality is not specified, the data will be fetched at the optimistic finality (the latest block height).

For block height and finality final, instead of calling the NEAR RPC directly, the VM uses the Social API Server to fetch the data.

Social API server indexes the data for SocialDB and allows to fetch the data at any block height with additional options.

It also allows returning more data than an RPC call because it's not restricted by the gas limit. In general, the API server also serves data faster than the NEAR RPC, because it doesn't execute the contract code in a virtual machine.

tip

While the data is fetching, Social.get returns null.


Social.getrโ€‹

Social.getr is just a wrapper helper for Social.get, it appends ** to each of the path pattern.

Loading...
Parameters
paramrequiredtypedescription
patternsrequiredstring / string[]the path pattern(s)
finalityoptional"final" / numberthe block height or finality
optionsoptionalobjectthe options object.
options object
  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_deleted (optional): whether to return deleted values (as null). Default is false.

Social.keysโ€‹

The keys method allows to get the list of keys that match a pattern. It's useful for querying the data without reading values.

It also has an additional options field that can be used to specify the return type and whether to return deleted keys.

Loading...
Parameters

Social.keys takes up to 3 arguments:

paramrequiredtypedescription
patternsrequiredstring / string[]the path pattern(s)
finalityoptional"final" / numberthe block height or finality
optionsoptionalobjectthe options object.
options object
  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • return_type (optional): either "History", "True", or "BlockHeight". If not specified, it will return the "True".
  • return_deleted (optional): whether to return deleted values (as null). Default is false.
  • values_only (optional): whether to return only values (don't include objects). Default is false.
tip

The Social API server supports custom options return_type: "History". For each matching key, it will return an array containing all the block heights when the value was changed in ascending order. It can be used for building a feed, where the values are overwritten.


Social.setโ€‹

Takes a data object and commits it to SocialDB. The data object can contain multiple keys, and each key can contain multiple values.

Importantly, a user can only commit to their own space in SocialDB (e.g. alice.near can only write in alice.near/**), except if given explicit permission by the owner of another space.

Each time a user wants to commit data, they will be prompted to confirm the action. On confirming, the user can choose to not be asked again in the future.

Loading...
Parameters

Social.set arguments:

paramrequiredtypedescription
datarequiredobjectthe data object to be committed. Similar to CommitButton, it shouldn't start with an account ID.
optionsoptionalobjectoptional object.
options object
  • force (optional): whether to overwrite the data.
  • onCommit (optional): function to trigger on successful commit. Will pass the data that was written (including accountID).
  • onCancel (optional): function to trigger if the user cancels the commit.
tip

By default Social.set will omit saving data that is already saved (e.g. if the user already liked a post, it won't save the like again). To force saving the data, pass the force option.


Social.indexโ€‹

NEAR Social readily provides an indexer - a service that listen to actions in SocialDB, and caches them so they can be retrieved without needing to interact with the contract.

The indexer is very useful, for example, to rapidly store and retrieve information on all comments for a post. Without the indexer, we would need to check all entries in the contract to see who answered, surely running out of GAS before completion.


Indexing an Actionโ€‹

To index an action we need to add the index key to the data being saved, within the index key we will save the action being indexed, alongside a key and a value that identifies this specific instance.

Loading...

In the example above we index a docs action. In this case the action is docs, and the key that identifies it is "read".

Standards

Indexing a Postโ€‹

To index a post, the standard is to save the action post, with {key: "main", value: {type: "md"}.

{
index: {
post: JSON.stringify({
key: "main",
value: {type: "md"}
})
}
}

Indexing a Likeโ€‹

To index a like, the standard is to save the action like, with {key: object-representing-the-post, value: {type: "like" }}

{
index: {
like: JSON.stringify({
key: {type: 'social', path: 'influencer.testnet/post/main', blockHeight: 152959480 },
value: {type: "like"}})
}
}

Retrieving Indexed Actionsโ€‹

To retrieve indexed actions we use the Social.index method. It takes the action and the key as arguments, and returns an array of all the indexed values alongside the blockHeight in which they were indexed, and which user made the action.

Loading...
Parameters

Social.index arguments:

paramrequiredtypedescription
actionrequiredstringis the index_type from the standard, e.g. in the path index/like the action is like.
keyrequiredstringis the inner indexed value from the standard.
optionsoptionalobjectthe options object.
options object
  • subscribe (optional): if true, the data will be refreshed every 5 seconds.
  • accountId (optional): If given, it should either be a string or an array of account IDs to filter values by them. Otherwise, not filters by account Id.
  • order (optional): Either asc or desc. Defaults to asc.
  • limit (optional): Defaults to 100. The number of values to return. Index may return more than index values, if the last elements have the same block height.
  • from (optional): Defaults to 0 or Max depending on order.
Was this page helpful?