Spatiotemporal indexing parameters

The spatiotemporal index parameters are defined as a BSON document. The parameters define how spatiotemporal data configured and the storage spaces and extent sizes for subtrack tables and their indexes.

Figure 1: Syntax of parameters

averageMovingGPSRate

How often a position reading is generated for a moving object.

The seconds value is a floating-point number, with a range greater than or equal to .001 and less than or equal to 1800, that represents the number of seconds between readings. Default is 60.

averageStationaryGPSRate

How often a position reading is generated for a stationary object.

The seconds value is a floating-point number, with a range greater than or equal to .001 and less than or equal to 1800, that represents the number of seconds between readings. Default is 60.

minStationaryInterval

How long an object must be in the same position to be considered stationary.

The seconds value is an integer 60-3600 that represents the number of seconds before stationary status. Must be greater than the value of the averageMovingGPSRate field. Default is 300.

maxStationaryDistance

The maximum distance an object can move and still be considered to be stationary.

The meters value is a float number greater than or equal to 0 that represents the maximum change in position for a stationary object. Default is 1.

fenceDistance

As the timeseries is processed by STS, it calculates the distance between two consecutive points.

If that distance is greater than the fenceDistance, an error is generated. Default is 0.0. A fenceDistance of 0.0 disables this parameter.

The meters value is a float number greater than 0 that represents the distance between two consecutive points.

fenceBox

Specifies a box around the area of interest.

In the array, the first value is llx: lower left x (or longitude), the second value is lly: lower left y (or latitude), the third value is urx: upper right x (or longitude) and the fourth value is the ury: upper right y (or latitude).

These values are in the coordinate system defined by the SRID BSON field, llx is less than urx and lly is less than ury. Values outside this bounding box will be ignored. This is used to only process data in the area of interest so no errors are generated. "no data" subtracks may be generated when the vehicle is outside the box.

Example

"fenceBox":[-80.00,43.00,-78.00,43.9],
"SRID":4326

specifies a box around the area of interest. STS will only consider Longitude coordinate values between -80 and -78 degrees and Latitude coordinate values between 43.0 and 43.9 degrees.

minNoDataInterval

How long an object has no readings to be in a no signal or an interrupted signal state.

The seconds value is an integer 60-14400 that represents the number of seconds before no signal or interrupted signal status. Must be greater than the value of the minStationaryInterval field. Default is 600.

maxGPSTimeIntervalPerTrajectory

The maximum amount of time for the trajectory of a moving object.

The seconds value is an integer 60-14400 that represents the maximum number of seconds for a trajectory. Default is 600.

maxMovingTrajectoryArea

The maximum area of the bounding box around a trajectory.

The square_meters value is a float number:

0.0 = Default. No area limit.
1.0 or greater = The square meters of the bounding box around the trajectory.

position

A string array that identifies the sources of the longitude and latitude values. You can specify two BSON paths that start with the same BSON column name, or two FLOAT column names.

The longitude value is the column name or the BSON path for the longitude data. Default is the second column, which must be of type FLOAT, in the TimeSeries subtype.

The latitude value is the column name or the BSON path for the latitude data. Default is the third column, which must be of type FLOAT, in the TimeSeries subtype.

For example, your TimeSeries subtype the following structure:

CREATE ROW TYPE mytsrow(
    tstamp DATETIME YEAR TO FRACTION(5),
    temp FLOAT,
    data BSON);

The BSON column has a document with this structure: {"sensor":{"position":{"lat":value,"long":value}}}. You set the position field to:

"position": ["data.sensor.position.long",
"data.sensor.position.lat"]

For example, your TimeSeries subtype has the following structure:

CREATE ROW TYPE mytsrow(
    tstamp DATETIME YEAR TO FRACTION(5),
    temp FLOAT,
    gpslat FLOAT,
    gpslong FLOAT);

You set the position field to:

"position":
["gpslong","gpslat"]

unitOfMeasure

The linear units of measure for trajectories specified by uom. It may be any linear unit of measure defined in the st_unit_of_measure table in the Spatial Data Type. For more information see, (Units of measure).

If unitOfMeasure is not specified, then it is meter for a geographic coordinate systems, and, it is the linear unit of measure for projected coordinate systems. If the projected coordinate system does not have a linear unit of measure specified, it is meter.

This linear unit of measure is the unit of measure for any length or area specified in the BSON parameters. Specifically:

maxStationaryDistance (in the linear unit of measure)
maxMovingTrajectoryArea (in the square of the linear unit of measure)
fenceDistance (in the linear unit of measure)

maxNearestCount

The count value is an integer that represents the default maximum number of rows to return from the STS_GetLocNearest function. Default is 10. You can override this value when you run the STS_GetLocNearest function.

SRID

The spatial reference identifier for trajectory objects. The spatial_ref_id must be a defined spatial referencing system in the spatial_references table. See Spatial References table.

Note: If SRID is not specified, then the default is 4326 (WGS 84) which is commonly used by most GPS devices.

treatAsEuclidean

Either 0 or 1. The default is 0. The spatial ST_Distance function is effectively used to calculate a distance between two points when the value is 0. For the value 1, the data must be in Euclidean space where the distance is calculated using Pythagorean theorem. If the points are not in Euclidean space and this parameter is enabled, unpredictable results will happen generating subtracks.

storage

Storage clauses for the subtrack tables and their associated indexes. Default is no storage clauses. The storage clauses require the syntax of the IN clause or the FRAGMENT BY clause of the CREATE TABLE and CREATE INDEX statements. See Storage options for tables and Storage options for indexes.

subtrack: The storage value is the storage clause for the subtrack tables.
subtrackGeometry: The storage value is the storage clause for the geometry columns in the subtrack tables.
subtrackPK: The storage value is the storage clause for the primary key indexes on the subtrack tables.
subtrackRT: The storage value is the storage clause for R-tree indexes on the subtrack tables. The storage spaces for R-tree indexes must all have the same page size.
subtrackET: The storage value is the storage clause for instance ID and end time indexes on the subtrack tables.
functionalIndex: The storage value is the storage clause for functional indexes on the time series instance IDs. The functionalIndexName parameter must be set.

extent

Extent size clauses for the subtrack tables and their associated indexes. Default is no extent clauses. The extent size clauses require the syntax of the EXTENT SIZE options of the CREATE TABLE and CREATE INDEX statements. See Extent size options for tables and Extent size options for indexes.

subtrack: The [first,next] integer values are the first and next extent sizes for the subtrack tables.
subtrackPK: The [first,next] integer values are the first and next extent sizes for the primary key indexes on the subtrack tables.
subtrackRT: The [first,next] integer values are the first and next extent sizes for R-tree indexes on the subtrack tables.
subtrackET: The [first,next] integer values are the first and next extent sizes for instance ID and end time indexes on the subtrack tables.
functionalIndex: The [first,next] integer values are the first and next extent sizes for functional indexes on the time series instance IDs. The functionalIndexName parameter must be set.

RTParameters

The Rtree_index_parameters value is a string that represents R-tree index parameters. Default is no R-tree index parameters. See R-tree index parameters.

functionalIndexName

The func_index_name value is a string that represents the name of the functional index on the time series IDs. A functional index on the time series instance IDs can speed processing. If you specify a name, the functional index is created. Default is no functional index.

transactionControl

An integer that specifies how to handle transactions for the Scheduler task and the STS_SubtrackCreate, STS_SubtrackDestroy, STS_SubtrackBuild, STS_SubtrackUpdate, and STS_SubtrackAlterProcessing subtrack processing functions:

-1 = An explicit transaction is automatically created. Default for the Scheduler task.
0 = You must create an explicit transaction when you run subtrack processing functions. Default for subtrack processing functions.
positive integer = An explicit transaction is automatically created that processes the specified number of time series values. This option can prevent long transaction failures when you index thousands or millions of time series values from the base table.

Default parameters

The following document represents the default parameters document:

{
"averageMovingGPSRate":60,
"minStationaryInterval":300,
"maxStationaryDistance":1,
"minNoDataInterval":600,
"maxGPSTimeIntervalPerTrajectory":900,
"maxMovingTrajectoryArea":0.0,
"unitOfMeasure":"meter",
"SRID":4326,
"transactionControl":0
}

The default values for the storage and extent parameters are to omit storage and extent clauses from the CREATE TABLE and CREATE INDEX statements. If you omit storage and extent clauses, the default storage spaces and extent sizes for the database are used.

By default the R-tree index parameters are omitted from the CREATE INDEX statement for the R-tree index.

By default, the functional index on the time series instance ID is not created.

When you set the parameters with the STS_SubtrackCreate or STS_SetDefaultParameters function, you specify only the parameters with non-default values.

Time units

Five parameters, averageMovingGPSRate, averageStationaryGPSRate, minStationaryInterval, minNoDataInterval, and maxGPSTimeIntervalPerTrajectory, can be specified either as a number or a string. For example: “averageMovingGPSRate":10 can also be specified as a string (“averageMovingGPSRate":"10"), for the same result. Additional functionality can be added by specifying an optional unit of time measure (represented as a string) after the number. To speed up processing, single characters are used: s for second, m for minute, h for hour and d for day. The same 10 second value mentioned above can also be specified as:

“averageMovingGPSRate":10
“averageMovingGPSRate": 10.0000
“averageMovingGPSRate":"1.0e1"
“averageMovingGPSRate":"10s"
“averageMovingGPSRate":".16666666m".

The leading and trailing spaces are removed from the string form of the parameter. The multiplier is set to 1.0 by default (seconds). If the last character of the string is s, the multiplier remains at 1.0. If it is m, the multiplier is 60. If it is h, the multiplier is 60*60, and if it is d, the multiplier is 24*60*60.

If there is any other character besides a period or digit, an error is generated. The preceding number is then converted to a floating point value, and the multiplier is applied. If this process fails, an error is generated.

For averageMovingGPSRate and averageStationaryGPSRate, the result is used as a real number.

For minStationaryInterval, minNoDataInterval, and maxGPSTimeIntervalPerTrajectory the result is cast to an integer and used.