Endpoint Overview#

Overview#

The query endpoint expects a body that represents a query with the following keys:

  • select (required)

  • from (optional)

  • subquery (optional)

  • filter (optional)

  • group_by (optional)

  • order_by (optional)

Property Types#

There are 2 types of properties that can be returned in the query response:

  1. “regular” properties - to select all of these at once time, you can use the * string

    • include all of the model’s attributes

    • inference_timestamp

    • received_timestamp

    • inference_id

    • partner_inference_id

    • ground_truth_timestamp (if ground truth is included)

    • batch_id (if batch model)

  2. “enriched” properties - you must specify these by name to include them in the response and use the from value enriched:

    • anomaly_score

    • lime_importance

    • shap_importance

‘From’ Sources#

There are 3 valid values for the from field:

  1. inference - The latest, raw inference data sent to the platform. This is the default.

  2. enriched - Every value from the inference data, with additional fields for anomaly scores and explanations. This data has some insert latency compared to the raw table.

  3. reference - The reference data set uploaded for the model.

Filter Field#

The filter field contains a list of filters to apply to your query. It takes the form:

{
  "filter": [
    {
      "property": "<property_name> [string]",
      "comparator": "<comparator> [string]",
      "value": "<value> [any]"
    },
     "..."
  ]
}

Filter Comparators#

The following filter comparators are available:

  • eq - Filters where the property field equals the value field.

  • ne - Filters where the property field is not equal to the value field.

  • lt - Filters where the property field is less than the value field. Only valid for number values.

  • gt - Filters where the property field is greater than the value field. Only valid for number values.

  • lte - Filters where the property field is less than or equal to the value field. Only valid for number values.

  • gte - Filters where the property field is greater than or equal to the value field. Only valid for number values.

  • in - Filters where the property field is equal to any value in a list of possible values

  • like - Filters where the property field is like the value field. This filter is only valid for property types of unstructured text.

  • NotNull - Filters where the property field is not null. Value field should be empty.

  • IsNull - Filters where the property field is null. Value field should be empty.

Object Detection Fields#

Computer Vision models with an Output Type of Object Detection have some special fields you can use when querying.

Bounding boxes are sent using the following form: [class_id, confidence, top_left_x, top_left_y, width, height]. While the fields aren’t named when sending data, you can access these nested fields when querying.

Using the following model as an example:

InputType: Image
OutputType: ObjectDetection
Attributes:
	name	            stage	           value_type
0	image	            PIPELINE_INPUT	   IMAGE
1	label	            GROUND_TRUTH	   BOUNDING_BOX
2	objects_detected	PREDICTED_VALUE	   BOUNDING_BOX

Example query fetching all bounding box fields

{
  "select": [
    {
      "property": "inference_id"
    },
    {
      "property": "objects_detected"
    }
  ]
}

The reponse will have 1 object per bounding box.

{
  "query_result": [
    {
      "inference_id": "1",
      "objects_detected.class_id": 0,
      "objects_detected.confidence": 0.6,
      "objects_detected.top_left_x": 23,
      "objects_detected.top_left_y": 45,
      "objects_detected.width": 20,
      "objects_detected.height": 30
    },
    {
      "inference_id": "1",
      "objects_detected.class_id": 1,
      "objects_detected.confidence": 0.6,
      "objects_detected.top_left_x": 23,
      "objects_detected.top_left_y": 45,
      "objects_detected.width": 20,
      "objects_detected.height": 30
    },
    {
      "inference_id": 2,
      "...": "..."
    }
  ]
}

You can also specify only a single nested field:

{
  "select": [
    {
      "property": "inference_id"
    },
    {
      "property": "objects_detected.class_id"
    },
    {
      "property": "objects_detected.confidence"
    }
  ]
}

The reponse will have 1 object per bounding box.

{
  "query_result": [
    {
      "inference_id": "1",
      "objects_detected.class_id": 0,
      "objects_detected.confidence": 0.6
    },
    {
      "inference_id": "1",
      "objects_detected.class_id": 1,
      "objects_detected.confidence": 0.6
    },
    {
      "inference_id": 2,
      "...": "..."
    }
  ]
}

Note

When supplying the bounding box specific fields in filters, group bys, or order bys the columns must also be supplied in the select clause in order for the query to succeed.

Token Likelihoods Attributes#

TokenLikelihoods attributes yield two queryable columns for that attribute with suffixes “_tokens”, and “_likelihoods” appended to the name of the attribute. For example, a model with a TokenLikelihoods attribute named “summary_token_probs” yields two queryable columns: “summary_token_probs_tokens” and “summary_token_probs_likelihoods” which represent an array of the selected tokens, and an array of their corresponding likelihoods.

Here, the query

    "select": [
        {
            "property": "summary_token_probs_tokens"
        },
                {
            "property": "summary_token_probs_likelihoods"
        }
    ]

may have response

{
    "query_result": [
        {
            "summary_token_probs_likelihoods": [
                0.3758265972137451,
                0.6563436985015869,
                0.32000941038131714,
                0.5629857182502747
            ],
            "summary_token_probs_tokens": [
                "this",
                "is",
                "a",
                "summary"
            ]
        },
    ]
}

Inference Search Examples#

Example 1: Inference ID#

Select all an inference’s non-enriched properties where inference_id is equal to e8cc429c-c4a6-425e-af09-7567fafdb17b (this is the id that returns when an inference that is sent to Arthur)

Query Request Body:

{
  "select": [
    {
      "property": "*"
    }
  ],
  "filter": [
    {
      "property": "inference_id",
      "comparator": "eq",
      "value": "e8cc429c-c4a6-425e-af09-7567fafdb17b"
    }
  ]
}

Query Response:

{
  "query_result": [
    {
      "inference_id": "e8cc429c-c4a6-425e-af09-7567fafdb17b",
      "partner_inference_id": "8734-3423",
      "attr1": "something"
    }
  ]
}

back to top

Example 2: Partner Inference ID#

Select all the inference’s non-enriched properties where the partner_inference_id is equal to 8734-3423 (this is the id that the user specifies to associate with an inference that is sent to Arthur)

Query Request Body:

{
  "select": [
    {
      "property": "*"
    }
  ],
  "filter": [
    {
      "property": "partner_inference_id",
      "comparator": "eq",
      "value": "8734-3423"
    }
  ]
}

Query Response:

{
  "query_result": [
    {
      "inference_id": "e8cc429c-c4a6-425e-af09-7567fafdb17b",
      "partner_inference_id": "8734-3423",
      "attr1": "something"
    }
  ]
}

back to top

Example 3: Timestamp Filters#

Select all the inference’s non-enriched properties and anomaly_score where inference_timestamp is greater than or equal to 2020-22-07T10:00:00 and less than 2020-22-07T11:00:00

Query Request Body:

{
  "select": [
    {
      "property": "*"
    },
    {
      "property": "anomaly_score"
    }
  ],
  "from": "enriched",
  "filter": [
    {
      "property": "inference_timestamp",
      "comparator": "gte",
      "value": "2020-07-22T10:00:00Z"
    },
    {
      "property": "inference_timestamp",
      "comparator": "lt",
      "value": "2020-07-22T11:00:00Z"
    }
  ]
}

Query Response:

{
  "query_result": [
    {
      "inference_id": "0001",
      "attr1": "something",
      "anomaly_score": 0.34,
      "inference_timestamp": "2020-07-22T10:01:23Z"
    },
    {
      "inference_id": "0002",
      "attr1": "something",
      "anomaly_score": 0.67,
      "inference_timestamp": "2020-07-22T10:02:55Z"
    }
  ]
}

back to top

Example 4: Batch ID Filter#

Select all of the inference’s non-enriched properties where inference_timestamp is greater than or equal to 2020-22-07T10:00:00 and less than 2020-22-07T11:00:00 and where batch_id is equal to batch1

Query Request Body:

{
  "select": [
    {
      "property": "*"
    }
  ],
  "filter": [
    {
      "property": "inference_timestamp",
      "comparator": "gte",
      "value": "2020-07-22T10:00:00Z"
    },
    {
      "property": "inference_timestamp",
      "comparator": "lt",
      "value": "2020-07-22T11:00:00Z"
    },
    {
      "property": "batch_id",
      "comparator": "eq",
      "value": "batch1"
    }
  ]
}

Query Response:

{
  "query_result": [
    {
      "inference_id": "0001",
      "attr1": "something",
      "batch_id": "batch1",
      "inference_timestamp": "2020-07-22T10:01:23Z"
    },
    {
      "inference_id": "0002",
      "attr1": "something",
      "batch_id": "batch1",
      "inference_timestamp": "2020-07-22T10:02:55Z"
    }
  ]
}

back to top

Example 5: Aliasing and Order By#

Select the inference_id, state, income, inference_timestamp, and health_score as predicted_health_score where inference_timestamp is greater than or equal to 2020-22-07T10:00:00 and less than 2020-22-07T11:00:00 and where state is equal to DC and income is greater than or equal to 50000 and less than 90000

Query Request Body:

{
  "select": [
    {
      "property": "inference_id"
    },
    {
      "property": "state"
    },
    {
      "property": "income"
    },
    {
      "property": "inference_timestamp"
    },
    {
      "property": "health_score",
      "alias": "predicted_health_score"
    }
  ],
  "filter": [
    {
      "property": "inference_timestamp",
      "comparator": "gte",
      "value": "2020-07-22T10:00:00Z"
    },
    {
      "property": "inference_timestamp",
      "comparator": "lt",
      "value": "2020-07-22T11:00:00Z"
    },
    {
      "property": "state",
      "comparator": "eq",
      "value": "DC"
    },
    {
      "property": "income",
      "comparator": "gte",
      "value": 50000
    },
    {
      "property": "income",
      "comparator": "lt",
      "value": 90000
    }
  ],
  "order_by": [
    {
      "property": "income",
      "direction": "desc"
    }
  ]
}

Query Response:

{
  "query_result": [
    {
      "inference_id": "e8cc429c-c4a6-425e-af09-7567fafdb17b",
      "state": "DC",
      "income": 75000,
      "predicted_health_score": 84.3,
      "inference_timestamp": "2020-07-22T10:02:55Z"
    },
    {
      "inference_id": "1b813f11-94b8-4b5d-b26d-bc1cbc99b708",
      "state": "DC",
      "income": 52000,
      "predicted_health_score": 79.6,
      "inference_timestamp": "2020-07-22T10:31:02Z"
    }
  ]
}

back to top