Skip to content
Support
  • There are no suggestions because the search field is empty.

Custom Tables

Custom tables in Vince Live let you store and manage data flexibly with minimal constraints.

General information

Custom tables in Vince Live offer flexible, API-driven storage and management of business data. They are schema-less except for user-defined primary keys, giving you control over structure and making it easy to access, update, and integrate your data as needed.

Searching

Searching in custom tables is flexible and efficient. You can look up records by their internal ID, search by one or more primary key values, or use a prefix filter (‘beginsWith’) to find records where the keys match a certain pattern. All searches are performed through dedicated API endpoints.
 

Response formatting 

It is possible to determine how the response should look like by using response transformation. Please see section on this in Common features - Response formatting
 

Selecting specific records

For custom tables of type UPSERT it is possible to extract a specific records in a few different ways.
 
Single record with _id
The _id is the internal id created by the database.
 

Availability 

Custom table types APPEND, UPSERT, REPLACE
 

Limitations

Result is of single record type.
 

API path

GET /v1/custom-tables/data/{tableName}/{id}
 

Example request  

GET /live/custom-tables/data/fake-users/ZmFrZS11c2VycyMwI0RBVEEjQWRyaWFubmFfSmVua2luczQ5QGdtYWlsLmNvbQ
 

Example response 

{
    "__id": "ZmFrZS11c2VycyMwI0RBVEEjQWRyaWFubmFfSmVua2luczQ5QGdtYWlsLmNvbQ",
    "__created": "2022-04-05T12:56:37.059Z",
    "__modified": "2022-04-05T12:56:37.059Z",
    "__modifiedBy": "USER-62144feb3fb54922a1204eccb8d67989",
    "firstName": "Vella",
    "lastName": "Otto",
    "country": "ES",
    "zipCode": "39390",
    "phone": "+47112730385",
    "email": "Adrianna_Jenkins49@gmail.com"
}
 

Records with primary key values 

Use this when you want to fetch data without knowing the internal id.
Can extract both single and multiple records.
 

Availability

Custom table types UPSERT only.

Limitations

Total URL length cannot exceed 8192 kb. Result is of list records type.
 

API path

Single record
 
GET /v1/custom-tables/data/{tableName}?records.{primaryKey1}={value1}&records.{primaryKey2}={value2} 
 
Multiple records
 
GET /v1/custom-tables/data/{tableName}?records[{index1}].{primaryKey1}={value1}&records[{index1}].{primaryKey2}={value2}&records[{index2}].{primaryKey1}={value1}&records[{index2}].{primaryKey2}={value2}
 

Example request 

// single
GET /v1/custom-tables/data/items?records.ItemNumber=308&records.Warehouse=001

// multiple
GET /v1/custom-tables/data/items?records[0].ItemNumber=308&records[0].Warehouse=001&records[1].ItemNumber=KK327&records[1].Warehouse=002
 

​Example response 

// single
 
{
"count": 1,
"items": [
{
    "__id": "am9uYXMwMDEjMCNEQVRBIzMwOCMwMDEjMTYyNDYyMDg4MTIwMzIwMDYwNjcwNQ",
    "__created": "2021-06-25T11:34:41.204Z",
    "__modified": "2021-06-25T11:34:41.204Z",
    "Status": "20",
    "ProductGroup": "ZZZZZ",
    "Warehouse": "001",
    "StorageMethod": 3,
    "ItemType": "Z10",
    "Buyer": null,
    "DescriptionProductGroup": "Product Group",
    "DescriptionItemGroup": "Item group",
    "Name": "Kesla 122ND & 305T, 12-ton 1",
    "Description2": "Upd Kesla 122ND & 305T, 12-ton 2 0210",
    "ItemNumber": "308",
    "ItemGroup": "ZZZZZZZZ",
    "Location": "YRA0101"
}
]
}
 
// multiple
{
"count": 2,
"items": [
{
    "__id": "am9uYXMwMDEjMCNEQVRBIzMwOCMwMDEjMTYyNDYyMDg4MTIwMzIwMDYwNjcwNQ",
    "__created": "2021-06-25T11:34:41.204Z",
    "__modified": "2021-06-25T11:34:41.204Z",
    "Status": "20",
    "ProductGroup": "ZZZZZ",
    "Warehouse": "001",
    "StorageMethod": 3,
    "ItemType": "Z10",
    "Buyer": null,
    "DescriptionProductGroup": "Product Group",
    "DescriptionItemGroup": "Item group",
    "Name": "Kesla 122ND & 305T, 12-ton 1",
    "Description2": "Upd Kesla 122ND & 305T, 12-ton 2 0210",
    "ItemNumber": "308",
    "ItemGroup": "ZZZZZZZZ",
    "Location": "YRA0101"
},
{
      "__id": "am9uYXMwMDEjMCNEQVRBIyZLS1RFU1QzMjcjMDAxIzE2MjQ2MjA4ODE3NDM3NDA1NzUxNjc",
      "__created": "2021-06-25T11:34:41.744Z",
      "__modified": "2021-06-25T11:34:41.744Z",
      "Status": "20",
      "ProductGroup": "ZZZZZ",
      "Warehouse": "001",
      "StorageMethod": 3,
      "ItemType": "Z10",
      "AllocationMethod": 2,
      "Buyer": null,
      "DescriptionProductGroup": "Product Group",
      "DescriptionItemGroup": "Item group",
      "Name": "Auto-Guide prepared + TwinTra",
      "Description2": "Upd Auto-Guide prepared + TwinTrac + QuickSteer 0203",
      "ItemNumber": "KK327",
      "ItemGroup": "ZZZZZZZZ",
      "Location": "YRA0101"
  }
]
}
  

Records that begins with 

This is used to list many records, where the primary keys starts with your input string. It uses the sequence of the defined primary keys to apply a filter.
 
Multiple keys can be concatenated using #, e.g. firstkey#secondkey
 

Availability

Custom table types UPSERT only.
 

Limitations

Total output cannot exceed 6 mb. Prefix is case sensitive. Result is of list records type.
Sequence of primary keys is important!
 

API path

GET /v1/custom-tables/data/{tableName}?beginsWith={prefix}
 

Example request

// single primary key (email)
GET /v1/custom-tables/data/fake-users?beginsWith=As

// multiple primary keys (email + country, separate using # )
GET /v1/custom-tables/data/fake-users?beginsWith=Asa83@yahoo.com#Swe
 

​Example response

// single primary key
{
    "count": 2,
    "items": [
        {
            "__id": "ZmFrZS11c2VycyMwI0RBVEEjQXNhODNAeWFob28uY29t",
            "__created": "2022-04-05T12:56:37.014Z",
            "__modified": "2022-04-05T12:56:37.014Z",
            "__modifiedBy": "USER-62144feb3fb54922a1204eccb8d67989",
            "firstName": "Althea",
            "lastName": "Rebekah",
            "country": "Sweden",
            "zipCode": "18470",
            "phone": "+47899125484",
            "email": "Asa83@yahoo.com"
        },
        {
            "__id": "ZmFrZS11c2VycyMwI0RBVEEjQXNzdW50YS5DcmVtaW5AeWFob28uY29t",
            "__created": "2022-04-05T12:56:36.981Z",
            "__modified": "2022-04-05T12:56:36.981Z",
            "__modifiedBy": "USER-62144feb3fb54922a1204eccb8d67989",
            "firstName": "Alanis",
            "lastName": "Liana",
            "country": "Norway",
            "zipCode": "11191",
            "phone": "+47512509199",
            "email": "Assunta.Cremin@yahoo.com"
        }
    ]
}

// multiple primary keys
{
    "count": 1,
    "items": [
        {
            "__id": "ZmFrZS11c2VycyMwI0RBVEEjQXNhODNAeWFob28uY29t",
            "__created": "2022-04-05T12:56:37.014Z",
            "__modified": "2022-04-05T12:56:37.014Z",
            "__modifiedBy": "USER-62144feb3fb54922a1204eccb8d67989",
            "firstName": "Althea",
            "lastName": "Rebekah",
            "country": "Sweden",
            "zipCode": "18470",
            "phone": "+47899125484",
            "email": "Asa83@yahoo.com"
        }
    ]
}
 

​Updating records

You can update records in custom tables using simple API calls. Full records can be updated by internal ID or primary keys, and you can also target and update specific objects within array fields—so there’s no need to resend the entire record. All updates are handled flexibly and efficiently via API.
 
Updating objects in an array
 
In some cases you might want to update a single object within an array, without providing the full records. This can be done via a specific endpoint,
array-items
and by providing the keys on which to identify the object to be updated.
 
If a match on the is not found in the array, it will be appended to the array.
 
To perform multiple updates in the same request, provide an array of update objects instead of a single object.
 

API Path

PATCH /v1/custom-tables/data/{tableName}/array-items/{pathToArray}
 

Example data

Table name: items
 
Primary keys company, item
 
{
"company": "AAA",
 "item": "BicyclePump",
 "status": "Available",
 "vendor": "Biltema",
 "warehouseDetails": [
   { "warehouse": "MAIN", "country": "NO", "qty": 12, "location": "B12" },
   { "warehouse": "MAIN", "country": "SE", "qty": 24, "location": "S500" },
   { "warehouse": "AIRPORT", "country": "DK", "qty": 0, "location": "ØL1" },
  ]
}
 
{"company":"AAA","item":"BicyclePump","status":"Available","vendor":"Biltema","warehouseDetails":[{"warehouse":"MAIN","country":"NO","qty":12,"location":"B12"},{"warehouse":"MAIN","country":"SE","qty":24,"location":"S500"},{"warehouse":"AIRPORT","country":"DK","qty":0,"location":"ØL1"},]}
 

​Example request 

To update the ARN warehouse quantity:
 
PATCH /v1/custom-tables/data/items/array-items/warehouseDetails
 
// body:
{
  "primaryKeyValues": {
  // these are the unique record identifiers
"company": "AAA",
"item": "BicyclePump",
  },
  "keys": {
  // these are the keys to which we identity the 
  // unique record in the `warehouseDetails` array
    "warehouse": "MAIN",
"country": "SE",
  },
  "value": {
  // note that `keys` will be merged together with `value`
  // to create the updated object
    "qty": 50,
"location": "S500",
"sale": true
  }
}
 
// resulting full record
{
"company": "AAA",
"item": "BicyclePump",
"status": "Available",
"vendor": "Biltema",
"warehouseDetails": [
{ "warehouse": "MAIN", "country": "NO", "qty": 12, "location": "B12" },
{ "warehouse": "MAIN", "country": "SE", "qty": 50, "location": "S50", "sale": true },
{ "warehouse": "AIRPORT", "country": "DK", "qty": 0, "location": "ØL1" },
]
}
 
 
PATCH /v1/custom-tables/data/items/array-items/warehouseDetails// body:{"primaryKeyValues": {// these are the unique record identifiers"company":"AAA","item":"BicyclePump",},"keys": {// these are the keys to which we identity the // unique record in the `warehouseDetails` array    "warehouse": "MAIN","country":"SE",},"value": {// note that `keys` will be merged together with `value`// to create the updated object    "qty":50,"location":"S500","sale":true}}// resulting full record{"company":"AAA","item":"BicyclePump","status":"Available","vendor":"Biltema","warehouseDetails":[{"warehouse":"MAIN","country":"NO","qty":12,"location":"B12"},{"warehouse":"MAIN","country":"SE","qty":50,"location":"S50","sale":true},{"warehouse":"AIRPORT","country":"DK","qty":0,"location":"ØL1"},]}
 
NOTE! The merged keys and value object will be the resulting object, it will replace the existing object if found.
 
NOTE! Even if a schema is provided on the custom table, and enforce Schema is set to true data validation will NOT be performed on the object you are inserting into the array.
 

Configuration

The configuration - internally called the table meta- defines the table “schema” and configuration.
 
All custom tables are actually schema-less, meaning they do not need any prior field definition, except for the fields that form the primary keys.
 
However, some UI features in Vince Live, especially in relation to Dashboards are designed to use the definitions in the columnConfig section.
 

Primary Keys

Primary keys are one or more fields that make the record unique. Every table need at least one primary key field.
 
Once defined, the primary keys can not be changed.
 
If you need to add or change the primary keys, you need to create a new table.
 

Deleting tables

When deleting tables, there is a delay of up to 6 hours when the actual table is deleted. Until then, a new table with the same name can not be created.
 
Data in the table is inaccessible from the time of deletion, and will be deleted some time before the 6 hour delay.
 

Update configuration of a custom table

If there is no data in the table you can update the configuration from the UI.
 
If you need to add a field to a custom table that has data in it already, you can use an API call to update the configuration.
 

API path

PATCH /v1/custom-tables/meta
 

Example request

{
    "c": "appconfig",
    "tableAlias": "appconfig",
    "primaryKeys": [
        "app",
        "key"
    ],
    "updateType": "UPSERT",
    "columnConfig": {
        "app": {
            "aliasName": "App",
            "dataType": "STRING"
        },
        "valueObj": {
            "aliasName": "valueObj",
            "dataType": "STRING"
        },
        "value": {
            "aliasName": "Value",
            "dataType": "STRING"
        },
        "key": {
            "aliasName": "Key",
            "dataType": "STRING"
        },
        "status": {
            "aliasName": "Status",
            "dataType": "STRING"
        },
        "anotherNewField": {
            "aliasName": "myNewField",
            "dataType": "STRING"
        }
    }
}