files/arthur-docs-markdown/user-guide/api-query-guide/endpoint_overview.md.txt

# 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.

(endpoint_overview_filter_field)=
### Filter Field

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

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

(endpoint_overview_filter_comparators)=
#### 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

```json
{
  "selects": [
    {
      "property": "inference_id"
    },
    {
      "property": "objects_detected"
    }
  ]
}
```

The reponse will have 1 object per bounding box.

```json
{
  "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:

```json
{
  "selects": [
    {
      "property": "inference_id"
    },
    {
      "property": "objects_detected.class_id"
    },
    {
      "property": "objects_detected.confidence"
    }
  ]
}
```

The reponse will have 1 object per bounding box.

```json
{
  "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.
```

## 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:

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

Query Response:

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

[back to top](#endpoint-overview)

### 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:

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

Query Response:

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

[back to top](#endpoint-overview)

### 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:

```json
{
  "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:

```json
{
  "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](#endpoint-overview)

### 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:

```json
{
  "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:

```json
{
  "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](#endpoint-overview)

### 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:

```json
{
  "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:

```json
{
  "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](#endpoint-overview)