Data Shapes
Data Shapes represent the data in your model. A Data Shape is a named set of field definitions and related metadata. Each field in a Data Shape has a data type. ThingWorx has a defined set of base types.
 |
In ThingWorx, some reserved names can not be used as Data Shapes Field names. For example, ThingShape, sourceType, location, source. key, tags, timestamp, and so on.
|
Data Shapes help you to create applications, because when an application consumes data, with the Data Shape definition, the application has built-in knowledge of how to represent the data set. For example, if you are putting data into a grid on a mashup, the grid knows what the data is like because of the Data Shape definition. The grid knows which fields are numbers, strings, or dates. When you configure how the grid should render the data, this knowledge of the data set makes the configuration much easier.
There are specific Things that are created to store data: streams, value streams, and data tables. When you define a data storage Thing, you must define a Data Shape (except value streams).
Data Shapes are used in more cases than just as definitions for streams, value streams, and data tables. Data Shapes are also used when you need to describe a data set. For example, when you define an infotable output for a service implementation, you use a Data Shape to describe the output result set. You can have a Thing property of type infotable, and you can also specify the Data Shape that describes the property.
When defining the fields of a data shape, at least one of the fields must be marked as the primary key.
• If you are using MSSQL as your persistence provider, the length of the value for the primary key (combined length of the values for primary keys, if more than one is marked as primary key) is limited to 128 characters. If the length of the value being set is more than 128 characters, one of the following error messages is shown, depending on the version of MSSQL you are using:
◦ MSSQL 2019:
Unable to Invoke Service AddDataTableEntries on testDataTable :
java.lang.RuntimeException: com.thingworx.common.exceptions.DataAccessException:
[1,018] Data store unknown error: [Error occurred while accessing the data provider.]
java.lang.RuntimeException: com.thingworx.common.exceptions.DataAccessException:
[1,018] Data store unknown error: [Error occurred while accessing the data provider.]
◦ MSSQL 2017:
Unable to Invoke Service AddDataTableEntries on testDatatable :
java.lang.RuntimeException: com.thingworx.common.exceptions.DataAccessException:
[22,001] String or binary data would be truncated.
java.lang.RuntimeException: com.thingworx.common.exceptions.DataAccessException:
[22,001] String or binary data would be truncated.
• PTC recommends that IMAGE field definition should not be marked as Primary Key. If it is marked as Primary Key, the following error is shown.
◦ For PostgreSQL:
com.thingworx.common.exceptions.DataAccessException:
[1,018] Data store unknown error: [Error occurred while accessing the data provider.] org.postgresql.util.PSQLException: ERROR: index row requires 22064 bytes, maximum size is 8191
[1,018] Data store unknown error: [Error occurred while accessing the data provider.] org.postgresql.util.PSQLException: ERROR: index row requires 22064 bytes, maximum size is 8191
◦ For MSSQL:
com.thingworx.common.exceptions.DataAccessException: [1,018] Data store unknown error: [Error occurred while accessing the data provider.]
|
Base Type
|
Description
|
||
|---|---|---|---|
|
BASETYPENAME
|
A valid BaseType name.
|
||
|
BLOB
|
A binary large object.
|
||
|
BOOLEAN
|
A true or false value.
|
||
|
DASHBOARDNAME
|
The name of a dashboard.
|
||
|
DATASHAPENAME
|
A reference to a Data Shape in the model, and therefore has special handling.
|
||
|
DATETIME
|
A formatted date and time.
|
||
|
GUID
|
Globally unique identifier.
|
||
|
GROUPNAME
|
A user group name.
|
||
|
HTML
|
HTML content.
|
||
|
HYPERLINK
|
A standard URL (e.g., www.ptc.com).
|
||
|
IMAGE
|
Binary data that can be rendered as an image.
|
||
|
IMAGELINK
|
A URL link to an image.
|
||
|
INFOTABLE
|
A standard representation of data in ThingWorx that is similar to a SQL result set. There are a number of built-in services for building, consuming, and parsing an infotable.
|
||
|
INTEGER
|
A number that can be written without a fractional component.
|
||
|
JSON
|
A JavaScript Object Notation object.
|
||
|
LOCATION
|
Standard World Geodetic System (WGS) 84 coordinate, expressed as [longitude, latitude], elevation.
|
||
|
LONG
|
The LONG type should be used when a range longer than the INTEGER base type provides is required.
|
||
|
MASHUPNAME
|
A reference to a ThingWorx mashup, and therefore has special handling.
|
||
|
MENUNAME
|
The name of a menu.
|
||
|
NOTHING
|
Contains nothing (void).
|
||
|
NUMBER
|
A number.
|
||
|
PASSWORD
|
A masked password value. See Passwords for more information. For information about encryption methods, see Encryption.
|
||
|
QUERY
|
A JSON object that includes an array of "filters.” Each filter should include "value," "type,” and "fieldname".
|
||
|
SCHEDULE
|
A cron based schedule, configured using the Schedule Editor.
|
||
|
STRING
|
Any amount of alpha numeric characters.
|
||
|
STYLETHEMENAME
|
A reference to a style theme and therefore has special handling.
|
||
|
TAGS
|
ThingWorx tag values.
|
||
|
TEXT
|
Any amount of alpha numeric characters. The difference with STRING is that TEXT is indexed.
|
||
|
THINGCODE
|
A numerical representation of a Thing containing a DomainID and InstanceID. For example, 2:1.
|
||
|
THINGNAME
|
A reference to a Thing and therefore has special handling.
|
||
|
THINGSHAPENAME
|
A reference to a Thing Shape in the model, and therefore has special handling.
|
||
|
THINGTEMPLATENAME
|
The name of a Thing Template.
|
||
|
TIMESPAN
|
A TimeSpan object represents a time interval (duration of time or elapsed time) that is measured as a positive or negative number of days, hours, minutes, seconds.
|
||
|
USERNAME
|
A reference to a ThingWorx user defined in the system.
|
||
|
VEC2
|
A collection of two numbers. For example, 2D coordinates x and y.
|
||
|
VEC3
|
A collection of three numbers. For example, 3D coordinates x, y, and z.
|
||
|
VEC4
|
A collection of four numbers. For example, 4D coordinates x, y, z, and w.
|
||
|
XML
|
An XML snippet or document.
|
Updating an Existing Data Shape
Consider the following implications if you want to update an existing Data Shape (changing field definitions, types, or primary key) after it has been defined:
• Inserting data after changing the Data Shape will work. However, the new rows will be mapped to the new Data Shape definition.
• When inserting data after changing the Data Shape, the primary key will work, but the integrity of existing keys will still be verified. When doing an insert, the key value is built by concatenating all field values that are marked as a primary key (in the order of the field definitions) into one field called key.
• Querying the rows after changing the Data Shape will make a best effort attempt to map field names and types to the result set. If the existing rows do not match the types or field names, the rows will still be included in the set, but without a value.