Using Data Explorer

Caution: Data Explorer is for advanced users! Deleting the wrong objects could make your project UNUSABLE! Do NOT DELETE ANYTHING (using the trash can icon at the left end of the row) found in the results unless you are very sure about it. After deletion, you cannot undo it. All changes are done instantly.

Note: Data Explorer appears as a (default) add-on for users with a role given access to Data Explorer. (See Defining Roles and Configuring Users.)

Note: For tips on using Data Explorer, select the info icon found above the Data Query search field.

About Haystack Tags

Tags are automatically attached to points of interest that appear in profiles and cards. In a device profile, if Point of Interest is checked, a “pointOfInterest” tag is attached to that point. If “trend” is checked, a “his” tag (the Haystack standard for history) is attached to that point. (See Assigning Device Profiles.)

The Data Explorer allows searching for Haystack tags in the database. Tags are name/value pairs associated with a point or property. Most tags (searched for in Data Explorer) are either a marker tag (generally what type of thing it is) or a “property” tag (some type of value of the thing).

The marker tag format is just the marker. Examples include:

  • point

  • air and temp

The general property tag format is tag==value. The value can be an ID or contiguous string. Strings with a space must be enclosed in double quotes. Examples include:

  • curVal>=50

  • dis==SPACE

  • dis=="METER 1"

To combine marker and property tags, the format is property tag==value and marker tag. Examples include:

  • dis==weeklySetpointChange and schedule

  • dis=="PRI ACTUAL FLOW" and bacnetCur==AV24

  • priority==warning and alarm (results would give only active alarms, not any that have been acknowledged)

Note: For general information about Haystack tags, see project-haystack.org/tag and project-haystack.org/doc/TagModel. See also the video KMC 101: What is Project Haystack?

Performing a Search

  1. Enter the query/search phrase in Data Query.

    Note: For more guidance about forming search phrases, see Tips for Queries.

  2. Select Search.

  3. Use the scroll bars to view all the columns and rows. (These change according to the kind of results.)

  4. Select the name of a column to sort the rows.

    Note: For more details about sorting, see Tips for Sorting.

Note: To optionally export and download search results as a CSV file, select Download CSV.

Note: A CSV file download will use the currently selected sort method for each page. The CSV file will contain all the records for the query term, but each page is sorted separately from other pages. Use the sort features in Excel to refine the order.

Tips for Queries

For best results, choose the most specific query string that returns concise but complete records.

Searches are case sensitive. If a search fails, check for capitalization issues.

Search supports and, or, == (equal), != (not equal), <, >, <=, >=, and phrases in (straight, not smart) quotes. Common search terms include: temp, humidity, sensor, point, device, schedule, alarm, space, air, dashboard, customDeck, trendSetting, sp (setpoints), his (histories or trends), dis (display names), and curVal (current values).

Note: Searches must pair a property tag with a value. Searching for just a property tag will not return results.

Valid types of searches would include these examples:

  • dis==REL_HUMIDITY

  • dis=="STE-6020 Temp. Sensor #10"

  • type==spaceTemperature

  • objectName==SPACE_SENSOR

  • dis=="ANALOG_VALUE"

  • curStatus!==ok

  • unit==°F

    Note: The degrees symbol ° can be created by pressing the Alt key while typing 0176 on the numeric keypad.

  • trendSetting and dis=="Voltage Meter"

  • message=="Who Changed the Setpoint?!"

  • occ==true

  • curStatus==down

  • deviceRef==06e1a461-209f-11e8-832a-f714c13eaeb1

  • modelName=="BAC-9311CE"

  • ip=="10.110.4.95"

Examples of database items that are not “points” are device, network, schedule, profile, trendSetting, and customDeck.

Tips for Sorting

Clicking a sort arrow sorts only the current page of multiple pages (if any). A fixed number of records are returned for each page. Use the left/right arrows at the bottom right to see other pages.

A selected sort tag will continue to sort other pages that are loaded, such as using the arrow/page buttons or starting a new search. The chosen sort tag is active until a new sort tag is chosen or the Data Explorer page is refreshed.

Sorting can be performed on marker and property tags but not for columns of lists (objects).

Adding Objects and Tags

Objects and tags can be added in Data Explorer if desired. A tag is a name and value pair applied to an entity that defines a fact or attribute about the entity. In Data Explorer, objects and tags can be added for storing values in the database that are not part of a device, for easier searching in Data Explorer of “favorite” objects, and for interfacing with APIs.

To add a new object:

  1. Select Add New Object.

  2. Select the appropriate tag Type from the drop-down box.

    Note: For tag type descriptions, see the table in Tag Types.

  3. Enter a Tag name (e.g., justDesserts) and (if not a Marker tag) a Value (e.g., Gooey Goodness and Justice).

  4. Select Submit.

    Note: This will create an object with one tag.

 

To add tags to the new (or an existing) object:

  1. Find the desired object by searching in Data Explorer.

  2. Select the + sign at the (left) end of its line (next to the trash can).

  3. Select the appropriate tag Type from the drop-down box.

    Note: For tag type descriptions, see the table in Tag Types.

  4. Enter a Tag name and (if not a Marker tag) a Value.

  5. Select Add.

  6. Search for the same object.

  7. Verify that the tag was created as intended and add more tags as desired.

Tag Types

Tag Type

Description

(Example) Name*

(Example) Value

Marker

A description that has no separate, associated value (usually used to indicate classifications or types of identity)

candyBar

(N/A)

Bool

A Boolean expression that is “true” or “false”

dessertTime

true

Number

An integer or floating point number

servings

4.5

Str

A string of Unicode characters (commonly used for human-read- able descriptions)

flavor

Milk Chocolate

Ref

A reference to another entity (requires a specific subset of ASCII characters: a-z, A-Z, 0-9, underscore, colon, dash, dot, or tilde)

dessertRef

1234abc

Coord

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

newParis_Ind

C(41.499998,-85.9833294)

 

*Tag names must:

  • Contain only ASCII letters, digits, or underscore (a-z, A-Z, 0-9, _).

  • Start with an ASCII lower-case letter (a-z).

  • Use camel case (e.g., yummyCandyBar) by convention.