DataLab secondary queries

DataLab has the ability to chain two queries so you can perform a secondary query against each found Entity in the primary one.

This effectively gives you for-loop like functionality to further isolate the specific records you want to work with.

Basics

The documentation for secondary queries matches the primary documentation. So we'll cover how to reference the primary query and what actions will be supported.

When specifying a criterion you can assign a .ValueOption property to equal "PRIMARY" as a way to indicate that the Operand should be referenced from the primary query.

Here is how you can find Entities near other Entities as an example. Note that this doesn't return the found result as it's two dimensional, instead it lets you perform an action against the result.

const postBody = {
    // Primary selection to first selection Entities in an Entity Type.
    "PrimarySelection": {
        "Items": [
            {
                "key": "EntityType",
                "EntityType": {
                    "EntityType.ID": "my-entities-1"
                },
                "LogicOperator": "AND"
            }
        ]
    }
    // Now we'll perform a secondary selection where these Entities are near the primary.
    "SecondarySelection": {
        "Items": [
            {
                "key": "attribute",
                "LogicOperator": "AND",

                // Attribute we're comparing from this query.
                "AttributePath: "Bruce/Location",

                // Location to compare this query to.
                // This is being referenced from the primary query due to the ValueOption.
                "ValueOption": "PRIMARY",
                "Operator": "NEAR BY",
                "OperandA": {
                    "AttributePath": "Bruce/Location"
                },

                // Distance in meters.
                "Distance": 500,
            }
        ]
    }
}

You can get a sample of the result against a specific Entity by specifying these properties.

const postBody = {
    "PrimarySelection": {
        ...
    }
    "SecondarySelection": {
        ...
    },
    // Specify the values to get a sample page of the secondary results.
    "PrimaryEntityID": "my-entity-id",
    "PrimaryEntityTypeID": "my-entity-type-id"
}

Action: Set attribute value

You can set a value on each found Entity in the secondary selection through the set-attribute action.

This will let you reference the relevant primary Entity for the value if you want to use that over a fixed value.

interface IAction {
    "ActionType": "set-attribute";
    // Performs some additional validation during the process based on the supplied value.
    // This will default to 'string' when unspecified.
    "AttributeType": "string" | "integer" | "double" | "datetime";

    // This is a Nextspace path string.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    "Path": string;

    // Specify "PRIMARY" to reference the related primary Entity for getting the value.
    // Specify "SAME_ENTITY" to reference the current Entity for getting the value.
    // Don't specify (or use 'CONST') to set a fixed value.
    "ValueOption": "PRIMARY" | "SAME_ENTITY";

    // Value to set.
    // When 'ValueOption' is 'CONST' this will be the value directy to set.
    // When 'ValueOption' is 'PRIMARY' this will be the path to get the value from the primary Entity.
    // When 'ValueOption' is 'SAME_ENTITY' this will be the path to get the value from the current Entity.
    "Value": {
        // Path to get the attribute from when the "ValueOption" is "PRIMARY".
        "AttributePath": string;
    }
}

Action: Merge Entities

This action will merge each secondary Entity into the corresponding primary Entity. The secondary Entities are not deleted. Specify the mapping below to dictate the merge logic.

interface IAction {
    "ActionType": "merge";
    // Data Mapping to apply between the found secondary Entities and the primary Entity.
    "DataMapping": IDataMapping;
}