.dataset().insert()

.dataset(...).insert(data: object): Promise<IData>

Insert a new row into a a given data set.

Parameters

  • data object
    The data that should be inserted into the data set for the new row's values. This will be an object that contains properties who's names start dp- for data points and l- for links. To get the data point id's please use the .dataset().schema() method or refer to the "ID" for the data point which can be found in the Data set inspector of the Data tab for the data set. The number of dp-{number} parameters will depend upon the number of data points configured for the data set. Each is optional (unless a "Required" validator is set for the data point) and will take the default value if not specified.

Returns

This method returns a Promise which will resolve to an object containing a data object with the data for the new row, if there are no errors, in the same structure as .dataset().data() method. Additionally, if any errors are reported there may be error and fieldError properties. If there are no errors, the error properties will not be present.

{
    "data": {
        "id": number,
        "dv": number,
        // ... data values
    },
    "error": string,         // General error information
    "fieldErrors": [
        {
            "name": string,  // Name of the data point in error
            "status": string // Error message
        }
    ]
}

Example

Consider the following being sent to our example data set for flights. It has a string field for the flight name and two links for the departure and arrival airports, in keeping with the example use for the data fetch examples:

const api = new CloudTablesApi('sub-domain', ':apiKey');

let result = await api.dataset(':id').insert({
	'dp-11': 'My Flight',
	'l-5': 11,
	'l-6': 3
});

Will result in the following JSON being stored in result:

{
	"data": {
		"id": 27,
		"dv": 0,
		"dp-11": "MyFlight",
		"l-5": [{
			"id": 11,
			"dp-8": "Aberdeen"
		}],
		"l-6": [{
			"id": 3,
			"dp-8": "Bristol"
		}]
	}
}