tengine:api

This is an old revision of the document!


This page provides details on how you can use TEngine via API calls

Used to create a new table. If the table already exists, it will error out. You must provide a partition key but a sort key is optional. You can also add additional indexes which also require a partition key and an optional sort key. Currently it's not possible to add indexes to an existing table.

Arguments

{
  tablename=STRING,
  pk=STRING
  sk=STRING  (optional)
 
  indexes={
    "string"={
      pk=STRING
      sk=STRING  (optional)
    }
  } (optional)
 
}

Return Format

{
  error=STRING
  success=BOOLEAN
}

Example Request

  temp.req = {};
 
  // Create a base table and two indexes
  // pk is mandatory, sk is optional
 
  temp.req.tablename = "player-test";
  temp.req.pk = "account";
  temp.req.sk = "sort";
 
  temp.req.indexes = {};
 
  temp.req.indexes.house_index = {};
  temp.req.indexes.house_index.pk = "housetype";
  temp.req.indexes.house_index.sk = "housesubtype";
 
  temp.req.indexes.location_index = {};
  temp.req.indexes.location_index.pk = "location";
 
  //create table 
  temp.r = TEngine.createtable(temp.req);
  if (temp.r.error) {
    printf("[TEngine Error]: %s", temp.r.error);
  } 

Example Return

{
   "success": 1,
   "error": ""
}

Retrieve a single item from the table based on the provided partition and sort key (where specified). If the item does not exist, it will not fail but instead, return an empty array. Get requests can not be made on an index: use the Query instead.

Request Format

{
  tablename=STRING
  keys={
    "string"=STRING
  }
}

Return Format

{
  error=STRING
  success=BOOLEAN
  result=OBJECT
}

Example Request

  temp.req = {};
  temp.req.tablename = "player-test";
 
  temp.req.keys.account = "Jane";
  temp.req.keys.sort = "housedata";
 
  temp.r = TEngine.get(temp.req);
  if (temp.r.error) {
    printf("[TEngine Error]: %s", temp.r.error);
  }

Example Return

{
   "success": 1,
   "error": "",
   "result": {"sample":"data"}
}

Queries can be made either on the base table or an index. It must be made on a partition key but the sort key is optional, even if the table is configured with a sort key. When the table/index only has a partition key, the single item with the matching partition key will be returned. If the table/index is configured with a partition key and sort key, it can provide every single item which matches the partition key. You can provide the sort key to return items matching the partiyion key and sort key (note that in an index, this can be multiple items)

You can also opt to provide conditions which will be tested on the sort key. Each condition will be tested and the item will only be returned if true to all conditions.

Conditions include begins_with - the sort key begins with the provided string > - the sort key is greater than the provided value (Note: compared as a string) < - the sort key is less than the provided value (Note: compared as a string)

Consider this table with the following items: … {pk: “item1”, sk: “sort_19”} {pk: “item1”, sk: “sort_20”} {pk: “item1”, sk: “sort_21”} {pk: “item1”, sk: “sort_22”} {pk: “item1”, sk: “sort_23”} {pk: “item1”, sk: “sort_24”} …

Example queries:

pk == item1 : will return all 6 items pk == item1 and sk == “sort_20” : will return the single matching item

pk == item1 and sk begins_with “sort_2” : will return the 5 items where sk starts with sort_2 pk == item1 and sk > sort_23 : will return just sort_24 since it's the only item > 23

Argument Format

{
  tablename=STRING
  keys={
    "string"=STRING
  }
}

Both methods use the same underlying method but the difference is:
Put: will either replace an existing item with the request or create a new item if it does not exist
Update: will either update an existing item with the request or create a new item if it does not exist

If the item matches any indexes in the table, the item will automatically be added to the index. If the item was previously in the index but no longer matches, it will be removed.

Argument Format

{
  tablename=STRING
  keys = {
    "string"=STRING 
  }
  data = {
    "string"=STRING
    "string"={}
    "string"=[]
  }
}

Return Format

{
  error=STRING
  success=BOOLEAN
}

Example Request

  temp.req = {};
  temp.req.keys.account = "Jane";
  temp.req.keys.sort = "housedata";
 
  temp.req.data.housetype="house1";
  temp.req.data.housesubtype="a1";
  temp.req.data.randomvariable="just because";
  temp.req.data.location="Elsewhere";
  temp.req.tablename="player-test";
  temp.r = TEngine.put(temp.req);
  if (temp.r.error) {
    printf("[TEngine Error]: %s", temp.r.error);
  }

Return Example

{
   "success": 1,
   "error": ""
}

Will delete the specified item from the table. If the table has indexes and the item was written to one or more indexes, it will also be deleted from the index

Argument Format

{
  tablename=STRING
  keys={
    "string"=STRING
  }
}

Return Format

{
  error=STRING
  success=BOOLEAN
}

Example Request

  temp.req = {};
  temp.req.tablename="player-test";
  temp.req.keys.account = "Jane";
  temp.req.keys.sort = "housedata";
  temp.r = TEngine.deleteitem(temp.req);
  if (temp.r.error) {
    printf("[TEngine Error]: %s", temp.r.error);
  }

Example Return

{
   "success": 1,
   "error": ""
}
Enter your comment. Wiki syntax is allowed:
 
  • tengine/api.1654737315.txt.gz
  • Last modified: 2022/06/09 01:15
  • by twinny