Skip to main content

Storage Api

By using the storage API, you can store custom data for your application.

To use the storage API, you need to define entities in the manifest.

Custom Entities​

Entities are stored as application data and can be manipulated using the storage API.

storage:
  entities:
    - name: <custom entity name>
      attributes:
        <attribute1>:
          type: <type>
        <attribute2>:
          type: <type>
        <attributeN>:
          type: <type>
      indexes:
        - <attributeN>
        - <attributeN>
caution

Fields in entities cannot be deleted. You can only add new fields or update attributes.

attribute type supports the following types​

  • String
  • Boolean
  • Date
  • Float

attribute also supports other properties​

  • required
  • defaultValue

For example:

storage:
  entities:
    - name: <custom entity name>
      attributes:
        <attribute1>:
          type: <type>
          required: true
          defaultValue: default-string

indexes​

Indexes support the creation of both regular and unique indexes.

Listing the field names directly will create a regular index. For example:

storage:
  entities:
    - name: <custom entity name>
      attributes:
        <attribute1>:
          type: <type>
        <attribute2>:
          type: <type>
        <attribute3>:
          type: <type>
      indexes:
        - attribute1,attribute2
        - attribute3

Two indexes will be created:

  1. A composite index on attribute1 and attribute2
  2. A single index on attribute3

You can also create a unique index, for example:

storage:
  entities:
    - name: <custom entity name>
      attributes:
        <attribute1>:
          type: <type>
        <attribute2>:
          type: <type>
        <attribute3>:
          type: <type>
      indexes:
        - name: unqiue_index_name
          fields:
            - attribute1
            - attribute2
          unique: true

Importing the Storage API​

To install the @giteeteam/apps-api, run:

npm install @giteeteam/apps-api

Import @giteeteam/apps-api:

import { storage } from "@giteeteam/apps-api";

Features​

  • Immutable: Each operation generates a new object
  • Chainable: Operations can be chained
caution

Since all operations are immutable, each operation will generate a new object. Therefore, it is recommended to use chainable operations to prevent loss of context in queries.

Query​

Basic Query​

const query = storage.entity("<custom-entity>").query();

query
  .equalTo("xxx", "xxx")
  .notEqualTo("xxx", "xxx")
  .greaterThan("playerAge", 18)
  .limit(10);

// query one
await query.first();
// query all
await query.find();

query.ascending("score");
query.descending("score");

// Restricts to wins < 50
query.lessThan("wins", 50);

// Restricts to wins <= 50
query.lessThanOrEqualTo("wins", 50);

// Restricts to wins > 50
query.greaterThan("wins", 50);

// Restricts to wins >= 50
query.greaterThanOrEqualTo("wins", 50);

// Finds scores from any of Jonathan, Dario, or Shawn
query.containedIn("playerName", [
  "Jonathan Walsh",
  "Dario Wunsch",
  "Shawn Simon",
]);

// Finds scores from anyone who is neither Jonathan, Dario, nor Shawn
query.notContainedIn("playerName", [
  "Jonathan Walsh",
  "Dario Wunsch",
  "Shawn Simon",
]);

// Finds objects that have the score set
query.exists("score");

// Finds objects that don't have the score set
query.doesNotExist("score");

query.select("score", "playerName");
// remove undesired fields while retrieving the rest:
query.exclude("playerName");

query.startsWith("name", "Big Daddy's");

Composite Query​

query = storage.entity("ItemRank").query();
query.equalTo("xxx", "xxx");

query2 = storage.entity("ItemRank").query();
query2.equalTo("xxx", "xxx");

storage.query.or(query, query2);

Aggregation Query​

await query.count();

Pagination​

// Limit the number of returned items
query.limit(100)；
// Skip items for pagination
query.skip(10)

Add/Update/Delete​

await storage.entity("<custom-entity>").add({
  name: "",
  values: {},
});

await storage.entity("<custom-entity>").set("objectId", {
  name: "",
  values: {},
});

await storage.entity("<custom-entity>").delete("objectId");