Add Rows#
Add rows to a datatable or subtable of a row. May also update individual or multiple rows in certain conditions.
POST https://api.cloudplan.net/api/tables/add_rows
Request Parameters#
{
"table_id": "",
"rows": [],
"update_many_filter": {},
"upsert": false,
"admin": false,
"sub_table_cx": "",
"sub_table_parent_row_id": "",
"sub_table_parent_row_filter": {}
}
table_id | (string)
Id of the table to use. If rows should be added to a sub-table this would be the id of the main/parent table.
rows | (list)
The rows that should be added to the table (except when other parameters like update_many_filter alter this functionality).
Two styles are available:
List of row objects:
"rows": [{"c10": "a value"}]List of list of values:
"rows": [["value0", "value1"]]
If a number series is configured in the table settings the generated series value will be added automatically as long as no other value is provided.
update_many_filter | (optional) (object)
Allows updates of multiple rows by matching them with this filter, see Query Filters for options.
If set rows must contain exactly one object that is used as update. Any values in this object will be written to the matched rows.
default: {}
upsert | (optional) (bool)
Used in combination with the update_many_filter. When enabled and no rows are matched by the filter the single row object from rows will be added to the table.
default: False
admin | (optional) (bool)
Perform permission check based on administrator status of the user. If calling user is an administrator it can access all tables within their organisation.
default: false
Additional Parameters for Subtable access
Only when targeting a subtable the parameters sub_table_cx and sub_table_parent_row_id are required. Sub tables are individual properties of row, so to target the individual cell in the table a row and column are needed. (E.g. positions in an invoice)
sub_table_cx | (string)
Defines the column where the subtable is stored.
default: empty
sub_table_parent_row_id | (string)
Add the rows to the subtable of this row
default: empty
sub_table_parent_row_filter | (optional) (object)
A filter that overrides the information given in sub_table_parent_row_id. The first matched (main-)row is used as a target. This can be useful if the row id is not known because the target is defined by its values rather than id.
default: {}
Behaviour with Unique Columns#
Columns of the table may have the unique property (See Datatable Object). If a new row contains a value that is already present in the table the row given in this request will be used to update the values of the existing row. Values will only be added and updated but not deleted from the existing row.
Behaviour with SQL Backed Tables#
Datatables which are configured to store data in an external SQL database generally behave the same as regular datatables, but there may be small differences in specific cases.
Reply Parameters#
{
"row_docs": [
{
"row_id": "67516C89B37D58C1A96E887A64D5F458",
"table_id": "67516C890DD0DCE7F2E39C4627E923F9",
"c0": "Some Value"
}
]
}
row_docs | (list of objects)
The list of row objects that were added. See Row Objects
If many rows were updated the first 100 modified rows are returned.
Examples#
Here are some examples for using get_rows. Some ids and paramters in the objects have been omitted for better readability.
Minimal Example
This example just adds some rows to a table
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"name": "example table"
"col_settings": {
"c0": {
"name": "Column 0 Integer",
"display_type": "integer"
},
"c1": {
"name": "Column 1 String",
"display_type": "string"
}
}
}
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"rows": [[12, "test value"]]
}
{
"result": true,
"row_docs": [
{
"c0": 12,
"c1": "test value",
"row_id": "6970E70DA9C716F32FDA9B3BEEFDD8DF",
"table_id": "65DEF49C682194B07F7F9FDB24948904"
}
]
}
Example with unique column
This this example continues from the minimal example but now has the c0 column configured as unique. We try to add a row with the same c0 value 12 which means we won’t generate a new row, instead the existing one will be updated. The c1 value from the request will be written into the existing row.
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"name": "example table"
"col_settings": {
"c0": {
"name": "Column 0 Integer",
"display_type": "integer",
"unique": true
},
"c1": {
"name": "Column 1 String",
"display_type": "string"
}
}
}
[
{"c0": 12, "c1": "test value"}
]
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"rows": [[12, "another value"]]
}
{
"result": true,
"row_docs": [
{
"c0": 12,
"c1": "another value",
"row_id": "6970E70DA9C716F32FDA9B3BEEFDD8DF",
"table_id": "65DEF49C682194B07F7F9FDB24948904"
}
]
}
Example which updates many rows at once
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"name": "example table"
"col_settings": {
"c0": {
"name": "Column 0 Integer",
"display_type": "integer",
"unique": true
},
"c1": {
"name": "Column 1 String",
"display_type": "string"
}
}
}
[
{"c0": 12, "c1": "test value"}
{"c0": 13, "c1": "some string"}
{"c0": 14, "c1": "yes yes"}
]
{
"table_id": "65DEF49C682194B07F7F9FDB24948904",
"rows": [{"c1": "overwrite"}],
"update_many_filter": {"c0": {"$gte": 13}}
}
[
{"c0": 12, "c1": "test value"}
{"c0": 13, "c1": "overwrite"}
{"c0": 14, "c1": "overwrite"}
]