Working with ZStorage

Introduction

Zstorage abstracts away a managed, replicated and high performance relational object storage thats accessible via apis in a object-oriented or even record oriented away.

ZStorage provides:

• record/object oriented api (save, get, put,get)
• http based api request
• Transaction/Batch Write to injest large amounts of data
• Configurable Tables & Fields
• Sofisticated Validations (through formulas)
• Formula Execution upon API Operations (Delete, Write and Update)
• Managed Replication, Backups & Conflict Resolution

Supported Fields

• Email Field
• Integer Field
• Encrypted Text
• Textarea
• Json Field
• Lookup Field
• Picklist
• Text Field
• Formula Field
• Currency Field
• Decimal Field

Record API Usage

Supose we have a Student table, comprised of the following fields:

• name (string)
• email (email)
• address (string)
• age (integer)

Create an record object

This is how we would issue a request to create a object.

var api = new APIService("zstorage", token);
var newObj = {
    apiName: "Student",
    fields:{
        name: "Joao Leon",
        email: "company@example.com",
        address: "Rev street, 3rd Building, City of Perkins, ... ",
        age: 25
    }
};

api.post("record/new", newObj)
.then(function (resp) {
    // resp contain fields and id
}, reject);

Update record

Update an existing record with new info. In this example we'll update the age to 29. This is how we would issue a request to create a object.

var api = new APIService("zstorage", token);
var upsert = {
    id: <objectId>,
    apiName: 'Student',
    fields:{
        age: 29
    }
};

api.put("record/"+upsert.id, upsert)
.then(function (resp) {
    // update is done
}, reject);

Delete Record

This is how you can delete the same record

var api = new APIService("zstorage", token);
var recordId='...'

api.delete("record/"+recordId, upsert)
.then(function (resp) {
    // update is done
}, reject);

Fetch Records

Here's how we would fetch the list of Students in descending order, from oldest to newer.

var api = new APIService("zstorage", token);

api.get("table/Student/records?limit=10&offset=0&sort_by=age desc")
.then(function (Resp) {
    // Resp.list
    // Resp.totalCount
})

Query Records

We can query records by filtering on fields with params

var api = new APIService("zstorage", token);
var filterObj = {
    Table:"Student",
    Projection: "name, age, address", // which columns to bring
    Limit: 10,
    Offset: 0,
    Filter: "age > :age",
    Params: {
        age: 20
    }
};

api.post("table/Student/records/query", filterObj)
.then(function  (resp) {
    // resp.list
    // resp.totalCount
}, reject);

Query on json fields

ZStorage table support composite fields which must be queried using the postgres json syntax.. Supposed we have a json field on this table named conf, and that this fields holds a json property named value.

This is how we would query all records which the conf json has the attribute value equals to COMPONENT.

var api = new APIService("zstorage", token);
var filterObj = {
    Table:"Student",
    Projection: "name, age, address", // which columns to bring
    Limit: 10,
    Offset: 0,
    Filter: "(conf\\:\\:jsonb)->>'value'='COMPONENT'",
    Params: {
    }
};

api.post("table/Student/records/query", filterObj)
.then(function  (resp) {
    // resp.list
    // resp.totalCount
}, reject);

Transactions

ZStorage supports write/insert only transactions with a max of 100 items per request. Transactions also do not execute any aditional logic as a normal create request, for instance:

• No validation rules are executed
• No Field Validation Rules are executed
• No integration to queue systems are available
• No automatic mapping from field name column name
• No type mapping, every field must be string field

Transaction context is an ideally unique, auto-generated context that aggregates all records performed on a single transaction.

The context can help on querying all transaction items.

Example: From our Student table suppose, that name has been asigned the column col1, age the column col2 and address col3. This is how we would construct a transaction to insert a batch of 2 new students.

var api=new APIService("object", token);
var Tx={
    Context: "MY_TRANSACTION_123",
    Items: [
        {
            SchemaId: 'Id of the table',
            Fields: {
                api_name: 'Student',
                col1: 'Mara Bara', // name field
                col2: '29', // age field
                col3: 'Adress Here'  // address field
            }
        },
        {
            SchemaId: 'Id of the table',
            Fields: {
                api_name: 'Student',
                col1: 'Jonh Canbera', // name field
                col2: '19', // age field
                col3: 'Adress Here'  // address field
            }
        },
    ]
};

api.RunTransaction(Tx)
.then(function (done_) {
    // done_ contain details
});

To find out the column for the fields, we can consult the table details:

You can see that for this particular table Estudante, we have two fields nome and idade which has are asigned to the columns col1 and col2 respectively.

Queue API

Queues are part of the ZStorage Api, and are deeply integrated with tables allowing writes to be transactionally propagated to Queues and allowing for a robust development framework for distributed applications, consumers, publishers and finalizers.

In the Building Integration Services tutorial, we saw how tables can be synced with Queues to allow for durable writes and propagated queue message publishing on one single transaction.

Publishing Messages

By Queue Id

const api = new APIService("zstorage", token);
const queueId='...';
const msgPayload = {
    handler: '_worker_handler_name',
    // ...
    // other attributes
}

api.post("queue/"+queueId+"/publish", msgPayload)
.then(function (Resp) {
    // message-id
    // queue-id
})

By Queue Name

const api = new APIService("zstorage", token);
const queueName='...';
const msgPayload = {
    handler: '_worker_handler_name',
    // ...
    // other attributes
}

api.post("queue/a/"+queueName+"/publish", msgPayload)
.then(function (Resp) {
    // message-id
    // queue-id
})