storage-sdk

Storage SDK

ONES provides plugins Storage capabilities.

ONES Entity Storage SDK allows you to query the data stored in these structures using various query conditions, or perform data management operations such as creating, updating, and deleting data.

Currently supported storage capabilities include: entity storage.

Requirements

ONES	@ones-op/sdk	@ones/cli
v6.31.0	v1.0.8	v1.40.10

Entity Storage SDK

Entity data needs to be initialized through entity definition.

The following examples all use demo entity configuration as an example usage:

config/plugin.yaml
storage:
  entities:
    - name: employee
      attributes:
        name:
          type: string
          length: 32
          required: true
        age:
          type: integer
          required: true
        deleted:
          type: boolean
          required: true
      indexes:
        - name: find_by_name
          range_attribute: name
        - name: find_by_age_in_deleted_partition
          range_attribute: age
          partition:
            - deleted

SDK preview

After defining the entity, you need to use Git to commit the code.

When you commit the code or package the plugin through the op command, the entity declaration format of config/plugin.yaml will be verified.

If the format is correct, when you are coding, the editor (Visual Studio Code) will prompt you how to use the entity storage SDK and its entity data type.

Create or update an entity data

Key need to be satisfied Entity key specification。
Entity data need to be satisfied Create or update entity data specification。

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').set('employee001', {
  name: 'Mike',
  age: 25,
  deleted: false,
})

Create or update entity data specification

The type of the entity data's attribute need to be satisfied custom attribute definition.

If Key does not exist, create the entity data:
- Required attribute, need to be provided.
- Attributes that declare default values, if missing, the entity data will be created with the default values.
If Key exists, update the entity data:
- Required attribute, need to be provided.
- Attributes that declare default values, if missing, keep the original attribute value unchanged.

Batch create or update entity data

BatchSet receive a set of data, some of which can be created and some updated. And each piece of data must meet the following requirements:

Key need to be satisfied Entity key specification。
Entity data need to be satisfied Create or update entity data specification。
In the same call, the entity data created in batches have the same creation timestamp.
When sorting by the creation timestamp of the data, the sorting results of the data with the same timestamp depend on the performance of the database.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').batchSet([
  {
    key: 'employee888',
    value: {
      name: 'Emma',
      age: 24,
      deleted: true,
    },
  },
  {
    key: 'employee222',
    value: {
      name: 'Neo',
      age: 28,
      deleted: false,
    },
  },
  {
    key: 'employee999',
    value: {
      name: 'Molly',
      age: 30,
      deleted: false,
    },
  },
])

Delete an entity data

Key need to be satisfied Entity key specification。
If Key does not exist, the SDK will not throw an error.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').delete('employee001')

Batch delete entity data

BatchDelete receive a set of data, and each piece of data must comply with:

Key need to be satisfied Entity key specification。
If Key does not exist, the SDK will not throw an error.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').batchDelete(['employee888', 'employee222'])

Get an entity data

Key need to be satisfied Entity key specification。
If Key does not exist, undefined is returned and the SDK will not throw an error.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee')
  .get('employee001')
  .then((data) => {
    console.log(data)
    console.log(data?.name)
    console.log(data?.age)
    console.log(data?.deleted)
  })

Return type:

backend/src/index.ts
type data = {
  name: string
  age: number
  deleted: boolean
}

Use entity query object

Entity query objects provide more query methods.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').query()

Get an entity data by entity query object

If the entity does not have any data, undefined is returned and the SDK will not throw an error.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee')
  .query()
  .getOne()
  .then((data) => {
    console.log(data?.key)
    console.log(data?.value)
    console.log(data?.value.name)
    console.log(data?.value.age)
    console.log(data?.value.deleted)
  })

Return type:

backend/src/index.ts
type data = {
  key: string
  value: {
    name: string
    age: number
    deleted: boolean
  }
}

Get entity data array by entity query object

If the entity does not have any data, an empty array is returned and the SDK does not throw an error.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee')
  .query()
  .getMany()
  .then((data) => {
    console.log(data.page_info.count)
    console.log(data.page_info.has_more)
    console.log(data.page_info.end_cursor)
    console.log(data.data[0].key)
    console.log(data.data[0].value)
  })

Return type:

backend/src/index.ts
type data = {
  page_info: {
    count: number
    has_more: boolean
    end_cursor: string
  }
  data: {
    key: string
    value: {
      name: string
      age: number
      deleted: boolean
    }
  }[]
}

Get entity data total number by entity query object

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee')
  .query()
  .count()
  .then((data) => {
    console.log(data)
  })

Return type:

backend/src/index.ts
type data = number

Set entity query length (default: 10)

The entity query object supports setting the entity query length.

Supported input range: [1, 1000].

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').query().limit(100).getMany()

Set entity query sort (default: ASC)

Entity query objects support setting entity query sorting.

You can only enter, Sort, sort enumeration, and its enumeration values are:

ASC
DESC

In Custom index definition

When no index is defined:
- Sort by the timestamp when the data was created.
When an index is defined:
- Sort by the attribute value of the partition of the index and the timestamp when the data was created.
When sorting by the timestamp when the data was created, the sorting result of data with the same timestamp depends on the performance of the database.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage
const { Sort } = entity

entity('employee').query().sort(Sort.DESC).getMany()

Set entity query cursor

Entity query objects support setting entity query cursors.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

const query = entity('employee').query().limit(10)

query.getMany().then((data) => {
  query
    .cursor(data.page_info.end_cursor)
    .getMany()
    .then((data2) => {
      console.log(data2)
    })
})

Set entity query index

In Custom index definition, setting entity query indexes is supported only for entities that have indexes defined.

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee').query().index('find_by_name')

entity('employee')
  .query()
  .index('find_by_age_in_deleted_partition', [false])
  .getMany()
  .then((data) => {
    // Mike
    // Neo
    // Molly
  })

Set entity query where condition

Only entities with indexes defined in entity definitions can support setting entity query conditions.

In addition, entity query objects must first set entity query indexes before supporting setting entity query conditions.

You can only enter WhereConditions, entity query condition method enumeration, and its method enumeration values are:

beginsWith
between
equalTo
greaterThan
lessThan
greaterThanEqualTo
lessThanEqualTo

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'

const { entity } = storage
const { WhereConditions } = entity

entity('employee')
  .query()
  .index('find_by_name')
  .where(WhereConditions.beginsWith('M'))
  .getMany()
  .then((data) => {
    // Mike
    // Molly
  })

entity('employee')
  .query()
  .index('find_by_age_in_deleted_partition', [true])
  .where(WhereConditions.greaterThan(0))
  .getMany()
  .then((data) => {
    // Emma
  })

SDK use specification

SDK call rule

Write timeout: 15 seconds
Query timeout: 5 seconds
Maximum number of records returned in a single call: 1000

SDK data writing specification

Entity data specification

SDK error handling

All entity operations are asynchronous.

For error handling of the following methods, please refer to the example usage:

set
batchSet
delete
batchDelete
get
getOne
getMany
count

Example usage:

backend/src/index.ts
import { storage } from '@ones-op/sdk/backend'
import type { EntityError } from '@ones-op/sdk/backend'

const { entity } = storage

entity('employee')
  .query()
  .getOne()
  .then((data) => {
    console.log(data)
  })
  .catch((error: EntityError) => {
    console.log(error.code)
    console.log(error.err_msg)
  })

async function hello() {
  try {
    const data = await entity('employee').query().getOne()
    console.log(data)
  } catch (err: any) {
    const error: EntityError = err
    console.log(error.code)
    console.log(error.err_msg)
  }
}

Return type:

backend/src/index.ts
type EntityError = {
  code: string
  err_msg: string
}

SDK error code

Error code	Description
EntityNameInvalid	Entity name is empty. Or contains illegal characters. Or exceeds maximum length limit.
EntityNotFound	Entity name does not exist in configuration.
EntityDataEmpty	Entity data cannot be empty.
EntityDataBatchLimit	Too much entity data.
EntityDataKeyInvalid	Key is empty. Or contains illegal characters. Or exceeds maximum length limit.
EntityDataKeyDuplicate	Duplicate key is not allow.
EntityDataValueAttrInvalid	Attribute name is empty. Or contains illegal characters. Or exceeds maximum length limit.
EntityDataValueAttrNotFound	Attribute name does not exist in configuration.
EntityDataValueEmpty	Value cannot be empty.
EntityDataValueInvalid	Value is illegal.
EntityDataStringValueTooLong	The value of the attribute of type string exceeds the maximum length limit.
EntityDataTextValueTooLong	The value of the attribute of type text exceeds the maximum length limit.
EntityDataAttrRequired	A required attribute is missing.
EntityDataValueTypeInvalid	The type of the attribute value does not match the defined type.
EntityDataIndexEmpty	The index cannot be empty.
EntityDataIndexNameInvalid	The index is empty. Or contains illegal characters. Or exceeds the maximum length limit.
EntityDataIndexNotFound	The index does not exist in configuration.
EntityDataPartitionValueInvalid	The attribute value in the custom index is empty or illegal.
EntityDataPartitionValueTypeInvalid	The type of the attribute value in the custom index does not match the defined type.
EntityDataPartitionValueTooLong	The attribute value in the custom index exceeds the maximum length limit.
EntityDataUniqueConstraintFailed	The data has a unique constraint error.
EntityDataWhereConditionValueTypeInvalid	The attribute value type of the entity query condition clause does not match.
EntityDataWhereConditionValueTooLong	The attribute value of the entity query condition clause exceeds the maximum length limit.
EntityDataPageCursorInvalid	The value of the entity query cursor is illegal.
EntityDataSortValueInvalid	The value of the entity query sort is illegal.
EntityDataPageLimitNotInRange	The value of the entity query paging length is illegal.
EntityDataAPITimeOut	The entity operation or query timed out.
MalformedJSON	JSON serialization failed.

Storage SDK​

Requirements​

Entity Storage SDK​

SDK preview​

Create or update an entity data​

Create or update entity data specification​

Batch create or update entity data​

Delete an entity data​

Batch delete entity data​

Get an entity data​

Use entity query object​

Get an entity data by entity query object​

Get entity data array by entity query object​

Get entity data total number by entity query object​

Set entity query length (default: 10)​

Set entity query sort (default: ASC)​

Set entity query cursor​

Set entity query index​

Set entity query where condition​

SDK use specification​

SDK call rule​

SDK data writing specification​

SDK error handling​

SDK error code​

Storage SDK

Requirements

Entity Storage SDK

SDK preview

Create or update an entity data

Create or update entity data specification

Batch create or update entity data

Delete an entity data

Batch delete entity data

Get an entity data

Use entity query object

Get an entity data by entity query object

Get entity data array by entity query object

Get entity data total number by entity query object

Set entity query length (default: 10)

Set entity query sort (default: ASC)

Set entity query cursor

Set entity query index

Set entity query where condition

SDK use specification

SDK call rule

SDK data writing specification

SDK error handling

SDK error code