Entity

An entity is a controller class to operate on a specific resource. Once a class entity is created through a connector, you can access a series of properties and methods provided by that class entity.

An entity contains CRUD-like methods to interact with the underlying blockchain data.

Currently, the MetaID SDK provides common basic entity calls based on the on-chain Twitter-like example application BitBuzz, including buzzEntity, fileEntity, likeEntity. If developers have their own customization needs, they can create their own data protocol on the MetaProtocols website, and the MetaID SDK will automatically create relevant entities for that protocol.

In the following sections, we will use a buzzEntity as an example to demonstrate how to use entities. It is basically the same as a tweet model in a Twitter-like application.

The entity class

The entity class contains the following properties and methods:

Properties

Name
name
Type
string
Description
Unique name of the entity.
Name
schema
Type
EntitySchema
Description
The underlying schema in JSON format defining the data structure of the entity. It's like a table schema in a database.

ASYNCList records of the entity

list()

This method allows you to fetch all records complying with this entity schema with pagination.

For example, if you're using a buzzEntity, you can list all buzzes that have been created and posted onchain.

Required parameters

Name
page
Type
integer
Description
The page number to fetch.
Name
limit
Type
integer
Description
Limit the number of records returned per page.

Optional parameters

Name
network
Type
string
Description
An optional parameter to specify the network to fetch records from. If not provided, the network maintained in the connector will be used.

Call

ASYNC

list()

// Create a buzzEntity with connector.use().
const Buzz: Entity = connector.use('buzz')

const buzzList = await Buzz.list()

// specify the page and limit
const buzzList = await Buzz.list({ page: 2, limit: 20 })

Return

{
  "status": "success",
  "page": 1,
  "limit": 10,
  "data": [
    {
      "txid": "SIuAFUNKdSYHZF2w",
      "body": "xgQQXg3hrtjh7AvZ",
      "createdAt": {
        "id": "WAz8eIbvDR60rouK",
        "username": "KevinMcCallister",
        "phone_number": "1-800-759-3000",
        "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
        "last_active_at": 705103200,
        "created_at": 692233200
      },
      "user": "It’s a nice night for a neck injury.",
    },
    {
      // ..
    }
  ]
}

ASYNCGet a specific record of the entity

one()

This method fetch one record with the entity schema by providing the record id.

Required parameters

Name
id
Type
string
Description
Unique identifier for the record.

Optional parameters

Name
network
Type
string
Description
An optional parameter to specify the network to fetch records from. If not provided, the network maintained in the connector will be used.

Call

ASYNC

one()

// get one buzz record by id
const oneBuzz = await Buzz.one({ id: 'SIuAFUNKdSYHZF2w' })

// get latest buzz record
const latestBuzz = await Buzz.one()

Return

{
  "status": "success",
  "page": 1,
  "limit": 10,
  "data": [
    {
      "txid": "SIuAFUNKdSYHZF2w",
      "body": "xgQQXg3hrtjh7AvZ",
      "createdAt": {
        "id": "WAz8eIbvDR60rouK",
        "username": "KevinMcCallister",
        "phone_number": "1-800-759-3000",
        "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
        "last_active_at": 705103200,
        "created_at": 692233200
      },
      "user": "It’s a nice night for a neck injury.",
    },
    {
      // ..
    }
  ]
}

ASYNCGet the total number of records

total()

This method fetches the total number of records complying with the entity schema.

Optional parameters

Name
network
Type
string
Description
An optional parameter to specify the network to fetch records from. If not provided, the network maintained in the connector will be used.

Call

ASYNC

total()

const buzzTotalCount = await Buzz.total()

Return

{
  "status": "success",
  "page": 1,
  "limit": 10,
  "data": [
    {
      "txid": "SIuAFUNKdSYHZF2w",
      "body": "xgQQXg3hrtjh7AvZ",
      "createdAt": {
        "id": "WAz8eIbvDR60rouK",
        "username": "KevinMcCallister",
        "phone_number": "1-800-759-3000",
        "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
        "last_active_at": 705103200,
        "created_at": 692233200
      },
      "user": "It’s a nice night for a neck injury.",
    },
    {
      // ..
    }
  ]
}

ASYNCCreate a new record of this entity

create()

This method creates a new record with the entity schema.

Required parameters

Name
id
Type
string
Description
Unique identifier for the record.

Optional parameters

Name
network
Type
string
Description
An optional parameter to specify the network to fetch records from. If not provided, the network maintained in the connector will be used.

Call

ASYNC

create()

const buzzTotalCount = await Buzz.total()

Return

{
  "status": "success",
  "page": 1,
  "limit": 10,
  "data": [
    {
      "txid": "SIuAFUNKdSYHZF2w",
      "body": "xgQQXg3hrtjh7AvZ",
      "createdAt": {
        "id": "WAz8eIbvDR60rouK",
        "username": "KevinMcCallister",
        "phone_number": "1-800-759-3000",
        "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg",
        "last_active_at": 705103200,
        "created_at": 692233200
      },
      "user": "It’s a nice night for a neck injury.",
    },
    {
      // ..
    }
  ]
}