Object indexing

Object indexing imports objects from your integration into the SquaredUp graph, making them available throughout the platform for searching, scoping, drilldowns, and RollUp-style dashboards.

How object indexing works

Each indexing definition contains one or more import steps. Each step:

  1. Calls a data stream
  2. Reads the returned rows
  3. Maps those rows into graph objects
  4. Imports those objects into SquaredUp

This allows you to transform almost any external dataset into indexed objects that can participate in the SquaredUp object graph.

Typical objects include: hosts, virtual machines, applications, services, kubernetes resources, users, and many, many more!

Index definition location

Index definitions live in the indexDefinitions/ folder of your plugin.

The first (and often only) file must be named:

default.json

Note

The folder is named indexDefinitions in the plugin structure, but older documentation and internal tooling may still refer to it as importDefinitions.

Example index definition

{
  "steps": [
    {
      "name": "Import vehicles",
      "dataStream": {
        "name": "vehicles",
        "id": "datastream-xxxxxxxxxx" // ID is needed when configuring this via the product UI
        "config": {}
      },
      "timeframe": "none",
      "objectMapping": {
        "id": "name",
        "name": "name",
        "type": { "value": "starwars-vehicle" },
        "properties": [
          "model",
          "manufacturer",
          "vehicle_class",
          { "vehicleId": "name" },
          { "crewCount": "crew" },
          { "maxSpeed": "max_atmosphering_speed" },
          { "owner": { "value": "Disney" } }
        ]
      }
    }
  ],
  "importFrequencyMinutes": 720
}

How to configure object indexing

Objects indexing is configured in the Configure Indexing window, accessed by clicking More options

> Configure indexing on the data source overview page.

Parameters

Parameter
Description
Indexing frequency (minutes)
Specify how often the indexing process should run. This controls how frequently objects are imported and updated in the SquaredUp graph. Defaults to 720 minutes (12 hours).
Index steps
Configure one or more import steps which define how data streams are queried and mapped into graph objects. Each step imports a specific object type or dataset into SquaredUp. See Object indexing for the full schema.

Properties

ImportDefinition properties

Property
Type
Description
steps
array
The import steps to run
importFrequencyMinutes
number (optional)
Time between imports in minutes. Defaults to 720 (12 hours)

ImportStepDefinition properties

Property
Type
Description
name
string
Human-readable label for logging
dataStream.name
string
The data stream to read from
dataStream.config
object (optional)
Data source config passed to the stream
dataStream.grouping / dataStream.filters
object (optional)
Processing controls — easiest to copy from tile config
scope
object (optional)
A graph query to limit which objects are in scope for this import step. Easiest to copy from the SquaredUp UI when configuring indexing
timeframe
string
Timeframe for the data stream call (e.g. "last24Hours", "none")
objectMapping
object
How to convert rows into graph objects

objectMapping properties

Property
Description
id
Column name containing a unique object ID
name
Column name containing the display name
type
Either a column name (string) or a fixed value ({ "value": "myType" })
properties
Additional columns to include as object properties — see example above for the various formats

Indexing tips

  • Use multiple steps to import different object types (e.g. one step for hosts, one for services)
  • Mark data streams used only for indexing with "visibility": "hidden" so they don't appear in the tile editor
  • If your object ID comes from a field like type/id, add an additional property for the raw ID rather than trying to split the string — when an ID is specified as id/sourceId, SquaredUp automatically prefixes it with the source type to ensure uniqueness

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket