Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
tengine:api [2022/06/09 00:49] – twinny | tengine:api [2023/04/23 06:35] (current) – twinny | ||
---|---|---|---|
Line 1: | Line 1: | ||
===== API Documentation ===== | ===== API Documentation ===== | ||
+ | |||
+ | ( I accidentally nuked all documentation so It's currently being rebuilt! May be some missing parts of old/invalid details ) | ||
This page provides details on how you can use TEngine via API calls | This page provides details on how you can use TEngine via API calls | ||
Line 8: | Line 10: | ||
=== Arguments === | === Arguments === | ||
+ | |||
<code javascript> | <code javascript> | ||
{ | { | ||
Line 13: | Line 16: | ||
pk=STRING | pk=STRING | ||
sk=STRING | sk=STRING | ||
- | | + | |
indexes={ | indexes={ | ||
" | " | ||
Line 20: | Line 23: | ||
} | } | ||
} (optional) | } (optional) | ||
- | + | ||
} | } | ||
+ | |||
</ | </ | ||
=== Return Format === | === Return Format === | ||
+ | |||
<code javascript> | <code javascript> | ||
{ | { | ||
Line 30: | Line 35: | ||
success=BOOLEAN | success=BOOLEAN | ||
} | } | ||
+ | |||
</ | </ | ||
=== Example Request === | === Example Request === | ||
+ | |||
<code javascript> | <code javascript> | ||
temp.req = {}; | temp.req = {}; | ||
- | + | ||
// Create a base table and two indexes | // Create a base table and two indexes | ||
// pk is mandatory, sk is optional | // pk is mandatory, sk is optional | ||
- | + | ||
temp.req.tablename = " | temp.req.tablename = " | ||
temp.req.pk = " | temp.req.pk = " | ||
temp.req.sk = " | temp.req.sk = " | ||
- | + | ||
temp.req.indexes = {}; | temp.req.indexes = {}; | ||
- | + | ||
temp.req.indexes.house_index = {}; | temp.req.indexes.house_index = {}; | ||
temp.req.indexes.house_index.pk = " | temp.req.indexes.house_index.pk = " | ||
temp.req.indexes.house_index.sk = " | temp.req.indexes.house_index.sk = " | ||
- | + | ||
temp.req.indexes.location_index = {}; | temp.req.indexes.location_index = {}; | ||
temp.req.indexes.location_index.pk = " | temp.req.indexes.location_index.pk = " | ||
- | + | ||
- | //create table | + | //create table |
temp.r = TEngine.createtable(temp.req); | temp.r = TEngine.createtable(temp.req); | ||
if (temp.r.error) { | if (temp.r.error) { | ||
printf(" | printf(" | ||
- | } | + | } |
</ | </ | ||
=== Example Return === | === Example Return === | ||
+ | |||
<code javascript> | <code javascript> | ||
{ | { | ||
Line 65: | Line 74: | ||
" | " | ||
} | } | ||
+ | |||
</ | </ | ||
- | ==== Put / Update | + | ==== Get ==== |
- | Both methods use the same underlying method but the difference is: \\ | + | 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 |
- | **Put**: will either replace an existing item with the request or create a new item if it does not exist \\ | + | |
- | **Update**: | + | |
- | If the item matches any indexes in the table, the item will automatically | + | === Request Format === |
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | tablename=STRING | ||
+ | keys={ | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Return Format === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | error=STRING | ||
+ | success=BOOLEAN | ||
+ | result=OBJECT | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Request === | ||
+ | |||
+ | <code javascript> | ||
+ | temp.req = {}; | ||
+ | temp.req.tablename = " | ||
+ | |||
+ | temp.req.keys.account = " | ||
+ | temp.req.keys.sort = " | ||
+ | |||
+ | temp.r = TEngine.get(temp.req); | ||
+ | if (temp.r.error) { | ||
+ | printf(" | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Return === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | ==== Query ==== | ||
+ | |||
+ | 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 | ||
+ | |||
+ | 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: " | ||
+ | {pk: " | ||
+ | {pk: " | ||
+ | {pk: " | ||
+ | {pk: " | ||
+ | {pk: " | ||
+ | ... | ||
+ | |||
+ | </ | ||
+ | |||
+ | Example queries: | ||
+ | |||
+ | * pk == item1 : will return all 6 items | ||
+ | * pk == item1 and sk == " | ||
+ | * pk == item1 and sk begins_with " | ||
+ | * pk == item1 and sk > sort_23 : will return just sort_24 since it's the only item > 23 | ||
=== Argument Format === | === Argument Format === | ||
<code javascript> | <code javascript> | ||
- | tablename=STRING | + | { |
- | keys = { | + | |
- | " | + | keys={ |
+ | " | ||
+ | } | ||
+ | sortorder=" | ||
+ | startat=INTEGER - if set, skips the number of items configured here before potentially read and returning items. Useful for pagination | ||
+ | limit=INTEGER - if set, limits the number of read/ | ||
+ | conditions=ARRAY of ARRAYS e.g. { {" | ||
} | } | ||
- | data = { | + | |
- | | + | </ |
- | | + | |
- | | + | === Return Format === |
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | | ||
+ | | ||
+ | | ||
+ | foundcount=INTEGER - how many items were intiially found | ||
+ | error=STRING | ||
} | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Request === | ||
+ | |||
+ | <code javascript> | ||
+ | tbd | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Return === | ||
+ | |||
+ | <code javascript> | ||
+ | tbd | ||
+ | |||
+ | </ | ||
+ | |||
+ | ==== Put / Update ==== | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | tablename=STRING | ||
+ | keys = { | ||
+ | " | ||
+ | } | ||
+ | data = { | ||
+ | " | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | |||
</ | </ | ||
=== Return Format === | === Return Format === | ||
+ | |||
<code javascript> | <code javascript> | ||
{ | { | ||
Line 96: | Line 238: | ||
success=BOOLEAN | success=BOOLEAN | ||
} | } | ||
+ | |||
</ | </ | ||
=== Example Request === | === Example Request === | ||
+ | |||
<code javascript> | <code javascript> | ||
temp.req = {}; | temp.req = {}; | ||
temp.req.keys.account = " | temp.req.keys.account = " | ||
temp.req.keys.sort = " | temp.req.keys.sort = " | ||
- | + | ||
temp.req.data.housetype=" | temp.req.data.housetype=" | ||
temp.req.data.housesubtype=" | temp.req.data.housesubtype=" | ||
Line 113: | Line 257: | ||
printf(" | printf(" | ||
} | } | ||
+ | |||
</ | </ | ||
Line 122: | Line 267: | ||
" | " | ||
} | } | ||
+ | |||
</ | </ | ||
+ | |||
+ | ==== DeleteItem ==== | ||
+ | |||
+ | 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 === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | tablename=STRING | ||
+ | keys={ | ||
+ | " | ||
+ | } | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Return Format === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | error=STRING | ||
+ | success=BOOLEAN | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Request === | ||
+ | |||
+ | <code javascript> | ||
+ | temp.req = {}; | ||
+ | temp.req.tablename=" | ||
+ | temp.req.keys.account = " | ||
+ | temp.req.keys.sort = " | ||
+ | temp.r = TEngine.deleteitem(temp.req); | ||
+ | if (temp.r.error) { | ||
+ | printf(" | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | === Example Return === | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | " | ||
+ | " | ||
+ | } | ||
+ | |||
+ | </ | ||
+ | |||
+ | ==== ListTables ==== | ||
+ | |||
+ | tbd | ||
+ | |||
+ | ==== DescribeTable ==== | ||
+ | |||
+ | tbd | ||
+ | |||
+ | ---- | ||
+ | |||
+ | ~~DISCUSSION~~ | ||
+ | |||
+ |