Schema reference

The GraphQL schema reference documentation.

Query

Query data from WideSky

Field Argument Type Description
haystack Haystack

Query the semantic/historical data from WideSky

Objects

Bool

Boolean “true” or “false”.

Field Argument Type Description
bool Boolean

Coord

Geographic coordinate in latitude/longitude formatted as C(lat,lng)

Field Argument Type Description
coord String

Geographic coordinate in latitude/longitude formatted as C(lat,lng) see https://project-haystack.org/doc/TagModel

geohash String

A geographic location into a short string of letters and digits. see https://en.wikipedia.org/wiki/Geohash

longitude Float

Measurement east or west of the prime meridian

latitude Float

Measurement north or south of the Equator

Date

An ISO-8601 date as year, month, day: 2011-06-07

Field Argument Type Description
date String

DateTime

A representation of date and time.

Field Argument Type Description
dateTime String

A Project Haystack dateTime. Formatted as ISO-8601 timestamp followed by time zone name. e.g. 2011-06-07T09:51:27-04:00 New_York

isoDateTime iso8601

ISO-8601 format

unixTime UnixTime

Unix timestamp in ms

time zone String

Haystack time zone see https://project-haystack.org/download/tz.txt

Entities

A collection of Entities - an abstraction for some physical objects in the real world. See https://project-haystack.org/doc/TagModel

Field Argument Type Description
history History

Retrieve the timeseries data from a list of entities.

entityLimit Int

The maximum number of entities to return

rangeAbsolute absoluteRange

The absolute date time range of the history to retrieve

rangeRelative relativeRange

The relative Time range of the history to retrieve

count Int!

Return the number of entities in this set

entity [Entity]

Perform more operations on the individual entity

search Entities

For each entity, search for more entities with a filter that also have a tag value {whereTag} that matches a tag value of the current entity {matchesTag} e.g. ‘equipRef->id’

filter HaystackFilter!

A Project Haystack search filter e.g. equip and siteRef->geoCity == “Chicago” See https://project-haystack.org/doc/Filters

whereTag String!

Search for entities that reference the current entity by {whereTag}. e.g. ‘equipRef->spaceRef

matchesTag String

The tag value to match e.g. ‘equipRef->id’. If not set then the current entity's id is used

limit Int

Restrict the total number of entities returned from the search

tagSummary [TagSummary!]!

A statistical view of the tags available in the system

tagFilter [String]

A list of tag names to filter

ref Entities

For each entity in this set, return the related entities linked by the nominated traversal path.

path String!

The path to traverse (ref or list kind) e.g. ‘equipRef’, or ‘equipRef->siteRef’

units String

Value of the ‘unit’ Tag if all entities match. Otherwise returns ‘mixed’

Entity

An abstraction for some physical object in the real world. See https://project-haystack.org/doc/TagModel

Field Argument Type Description
description String!

Description of the entity

id ID!

Identifier of the entity

name String!

Name of the entity

fullyQualified Boolean

Name as Fully Qualified name. e.g. site.equip.point

search Entities

Search for entities with a filter that also have a Tag Value {whereTag} that matches a tag value of the current entity {matchesTag} e.g. ‘equipRef->id’

filter HaystackFilter!

A Project Haystack search filter. equip and siteRef->geoCity == “Chicago” See https://project-haystack.org/doc/Filters

whereTag String!

Search for entities that reference the current entity by {whereTag}. e.g. ‘equipRef->spaceRef’

matchesTag String

The tag value to match e.g. ‘equipRef->id’. Leave empty for the current Entity id

limit Int

The maximum number of entities to return

tags [Tag!]!

Lookup the tags of this entity

tagFilter [String]

A list of tag names to filter

refEntity Entity

Return the neighbour entity of the nominated ref tag e.g. equipRef

refTag String!

A ref tag to traverse. e.g. ‘equipRef’

ref Entities

Return the related entities linked by the nominated traversal path.

path String!

A path to traverse (ref or list kind) e.g. ‘equipRef’, or ‘equipRef->siteRef’

history History

Retrieve the timeseries data from the entity.

rangeAbsolute absoluteRange

The absolute date time range of the history to retrieve

rangeRelative relativeRange

The relative Time range of the history to retrieve

units String

Return the unit of measurement for this entity

Haystack

Query data from WideSky

Field Argument Type Description
search Entities

Search for entities

filter HaystackFilter!

A Project Haystack search filter

limit Int

Restrict the total number of entities returned from the search

entity Entity

Lookup an entity from its uuid or fully qualified name (site.equip.point)

id String!

The identifier value, an uuid or fully qualified name.

History

Field Argument Type Description
aggregate History

Take values and aggregate them in some way

function aggregations!

The Boolean scalar type represents true or false

allEntities Boolean

Apply to all entities or per entity

groupBy groupBy

Group by Time

select History

Return one or more records based on function logic

function Selectors!

The function logic

n Int

Value associated to the specified function logic

allEntities Boolean

Apply to all Entities or per Entity

groupBy groupBy

Group by Time

delta History

Value difference between timestamps

nonNegative Boolean

If set to true then only positive values are returned

allEntities Boolean

Apply to all entities or per entity

groupBy groupByAggregate

Group by Time

movingAverage History

The rolling average across a window of rolling periods.

n Int!

The number of points values associated to a rolling period. Note: ‘n’ must be greater than 1.

allEntities Boolean

Apply to all entities or per entity

groupBy groupByAggregate

Group by Time

applyConstant History

Apply a constant. E.g. ({value} * 1000) to all values for all entities.

math mathOptions!

Value rank entities by their aggregated history

entityFilter Entities

Filter entities that have record count of one or more.

rankOption rankOption

Value rank entities by their aggregated history

numberFilter History

Filter number values based on the defined conditions

conditionLogic conditionLogic

A set of conditions joined via logical OR

conditions [numberCondition]

A set of conditions joined via logical OR

boolFilter History

Filter values based on the Bool value

Bool Boolean!

The Boolean scalar type represents true or false

strFilter History

Filter str values based on the defined conditions

conditionLogic conditionLogic

A set of conditions joined via logical OR

conditions [strCondition]

A set of conditions joined via logical OR

timeSeries [TimeSeries]

The history time series

List

List of zero or more values represented as strings

Field Argument Type Description
listJSON String!

JSON based list content

list [tagKind]!

Formatted list content

Marker

A Marker the tag is merely a marker annotation and has no meaningful value. Marker tags are used to indicate a “type” or “is-a” relationship.

Field Argument Type Description
isMarker Boolean!

Number

A Number with an optional unit of measurement

Field Argument Type Description
value Float

Ref

Reference to another entity

Field Argument Type Description
ref String

Str

A string of Unicode characters.

Field Argument Type Description
str String

Tag

Field Argument Type Description
name String!

Name of the tag

value String

The value of the tag converted to String.

kindValue tagKind

The unconverted value of the tag see Tag Kinds https://project-haystack.org/doc/TagModel#tagKinds

TagSummary

A summary view of a particular tag across multiple entities

Field Argument Type Description
count Int

Number of time the tag is defined

name String!

Name of the Tag

values [String]

A list of values for each tag instance, converted to String.

distinct Boolean
kind String

The tag kind. E.g. Marker/String/Number…

kindValues [tagKind!]

An unconverted list of values for each tag instance.

distinct Boolean
aggregation tagValueAggregation

Aggregate Num values

Time

An ISO-8601 time as hour, minute, seconds: 09:51:27.354

Field Argument Type Description
time String

TimeSeries

Field Argument Type Description
dataPoints [dataPoint]

The history data points

Uri

A Universal Resource Identifier

Field Argument Type Description
uri String

dataPoint

Field Argument Type Description
time UnixTime

Time of the datapoint.

value String

Value of the datapoint converted to string.

valueKind pointKind

Value of the datapoint converted to its actual data type.

Inputs

absoluteRange

Specify an absolute time range

Field Type Description
start iso8601

Start time of the range (inclusive). E.g. 2019-04-29T03:00:00+00:00

end iso8601

End time of the range (exclusive). E.g. 2019-05-10T09:00:00+00:00

constantBySearch

Query for an aggregated set of tag values relative to the current entity. See option whereTag and matchesTag for more information on how the system performs the lookup for relative entities.

Field Type Description
filter String!

A haystack search query to further filter down the search result resolved using the ‘whereTag’ and ‘matchesTag’. Leave blank if no further filter is needed.

whereTag String

This option is for telling the system how the ‘relative entity’ will be referencing the current entity.

            E.g. If the whereTag is set as "spaceRef" and the matchesTag is set as "Id".
            Then in order for an entity to be qualified as relative entity, it must;

            1) Contain the spaceRef tag
            2) The spaceRef tag value must be equvalent to the current entity's "id" tagvalue.
            Assuming matchesTag is set as "Id"
matchesTag String

This option is for indicating how a relative entity will use its ‘whereTag’ value (See option whereTag) to match up with the current entity. If this is left as unset then the system defaults it to the “id” tagvalue. E.g. use case is that the whereTag is set as the equipRef of the point. In such case the equipRef id can then be used to find the relative entities that references the point's equip.

limit Int!

Limit of entities to match

tag String!

Tag values to use for the matched entities e.g. ‘area’

aggregation tagValueAggregation!

Aggregation of tags

constantByTraverse

Traverse to an entity by a ref tag. e.g. equipRef

Field Type Description
ref String

Return the entity of the nominated ref e.g. ‘equipRef->spaceRef’. Leave blank for the current Entity

tag String!

Value to use for the traversed entity e.g. ‘area’

aggregation tagValueAggregation!

Aggregation of tags

distinct Boolean

If true then only use an unique tag value once in the aggregation calculation. Example: If the ‘tag’ option is set as ‘area’ and a list of area value was resolved as [ 100, 200, 200, 300 ]. If the distinct optoin is set as ‘true’ then the system will only use the unique values from the set for aggregation. That is if the ‘aggregation’ option is set as SUM, then the result would be 600. Since 100 + 200 + 300 = 600

             Note: This option must be used in conjuction with the "aggregation" option.

groupBy

Group history by a specified time interval

Field Type Description
groupByUnits duration!

Units to group by.

groupBySize Int!

Number of units to group by

fill fillOption

Changes the value reported for time intervals that have no data

offset timeOffset

Shifts forward or back the preset groupBy time boundaries (UTC) by the nominated time duration. If offset { direction:AFTER offsetUnits:MINUTES offsetSize:900 } groupByUnit = WEEK groupBySize = 1 The data is group by the time(UTC + 900m), the boundary is now Sunday midnight in local Brisbane time.

                 Note: This option takes precedence over the offsetPointTz option.

groupByAggregate

Group history by a specified time interval and aggregate each interval as input for some Transformation functions

Field Type Description
groupByUnits duration!

Units to group by.

groupBySize Int!

Number of units to group by

fill fillOption

Changes the value reported for time intervals that have no data

aggregateFunction aggregateFunction!

Aggregation method for each group.

offset timeOffset

Shifts forward or back the preset groupBy time boundaries (UTC) by the nominated time duration. if offset{ direction:AFTER offsetUnits:MINUTES offsetSize:900 } groupByUnit = WEEK groupBySize = 1 The data is group by the time(UTC + 900m), the boundary is now Sunday midnight in local Brisbane time.

mathOptions

Apply a constant to all values

Field Type Description
operator operator!

Operator to apply

constant Float

Constant value

constantByTraverse constantByTraverse

Single tag value from the asset model relative to the Entity

constantBySearch constantBySearch

Aggregated tag values from the asset model relative to the Entity

orderSwap Boolean

Swaps the order of operation. False = ({value} / {constant}) ; True = ({constant} / {value})

numberCondition

It allows you to group sets of condition and join them using logical conjuctions such as AND or OR.

Field Type Description
operator numberComparisonOperator!
compareValue Float

Value to compare

rankOption

Field Type Description
rankType rankTypes

Type of rank

n Int!

Number of entities to return

aggregation aggregateFunction!

Method to aggregate

relativeRange

Define a time range by specifying a duration (in the past) relative to the server's current time, e.g. now() - 1h

Field Type Description
size Int!

Number of time units before now()

timeUnit duration!

End time of the range (exclusive).

offset timeOffset

Offset the range

strCondition

It allows you to group sets of condition and join them using logical conjuctions such as AND or OR.

Field Type Description
operator strComparisonOperator!

Operator to use in the condition

compareValue String

Value to compare

timeOffset

Field Type Description
direction relativePosition!

Direction to shift

offsetUnits duration!

Units of the duration.

offsetSize Int!

Duration size

Enums

Selectors

Value Description
FIRST

Value with the oldest timestamp

LAST

Value with the most recent timestamp

MAX

Greatest value

MIN

Lowest value

TOP

Greatest N values

BOTTOM

The smallest N values

PERCENTILE

Nth percentile values

aggregateFunction

Aggregation function

Value Description
MIN

The minimum of all records

MAX

The maximum of all records

MEAN
MEDIAN

The median of all records

MODE

The mode of all records

SUM

The Sum of all records

FIRST

The first record

LAST

The last record

COUNT

The number of records

aggregations

Aggregate functions that take values and aggregate them in some way

Value Description
COUNT

Number of values

DISTINCT

List of unique values

MEAN

Arithmetic mean (average) of values

MEDIAN

Middle value from a sorted list of values. The average value of the two middle field values is returned if the field contains an even number of values.

MODE

Most frequent value

SPREAD

Difference between the minimum and maximum values

STDDEV

Standard deviation of values

SUM

Sum of values

conditionLogic

Logical conjunction used to check that two conditions within a group are true

Value Description
AND
OR

duration

Time duration

Value Description
MILLISECOND

Millisecond (1 thousanth of a second)

SECOND
MINUTE
HOUR
DAY
WEEK

fillOption

Changes the value reported for time intervals that have no data

Value Description
LINEAR

Reports the results of linear interpolation for time intervals with no data.

NONE

Reports no timestamp and no value for time intervals with no data.

NULLVALUE

Reports null for time intervals with no data but returns a timestamp.

PREVIOUS

Reports the value from the previous time interval for time intervals with no data.

numberComparisonOperator

Operators for number kind

Value Description
EQUAL_TO

Equal

NOT_EQUAL_TO

Not Equal to

GREATER_THAN

Greater than.

GREATER_THAN_OR_EQUAL_TO

=

LESS_THAN

<

LESS_THAN_OR_EQUAL_TO

<=

operator

Operation to apply

Value Description
ADD

Perform addition

DIVIDE

Perform division

MULTIPLY

Perform multiplication

SUBTRACT

Perform subtraction

rankTypes

Ways to order ranking of entities

Value Description
BOTTOM

Entities with lowest aggregation value

TOP

Entities with highest aggregation value

relativePosition

A relative position in time

Value Description
FORWARD
BACK

strComparisonOperator

Operators for str kind

Value Description
EQUAL_TO

=

NOT_EQUAL_TO

â‰

REGEX_MATCHES

=~

REGEX_DOESNT_MATCH

!~

tagValueAggregation

Aggregation functions for multiple tag values

Value Description
SUM

The Sum of all value

MAX

Greatest value

MIN

Lowest value

MEAN

The median of all records

Scalars

Boolean

The Boolean scalar type represents true or false.

Float

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

HaystackFilter

A Project Haystack filter e.g. equip and siteRef->geoCity == “Chicago”, see https://project-haystack.org/doc/Filters

ID

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

UnixTime

Number of milliseconds elapsed since 1970-01-01T00:00:00.000Z.

iso8601

A dateTime represented in ISO-8601 format e.g. 2019-04-29T03:23:38+00:00 see https://en.wikipedia.org/wiki/ISO_8601