ThingWorx Model Definition and Composer > Data Shapes
  
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.
Data shapes help you to create applications, because when you consume data, the application has built-in knowledge of how to represent the data set because of the data shape definition. 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 wherever 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.
Field Definition Base Types
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.
* 
If using GUID as the Base Type, it is recommended to set the GUID value. Do not leave blank (default).
GROUPNAME
A user group name.
HTML
Some HTML content.
HYPERLINK
A standard URL (e.g., www.thingworx.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.
* 
Exponential values are allowed. For example, 123e45.
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 Strings 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
If a data shape is defined and there is an attempt to update the existing shape (changing field definitions, types, or primary key) the following implications should be considered:
Inserting data after changing the data shape will work, however, the new rows will be mapped to the new data shape definition.
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.