SageMaker Inference

Plugin parameters can be provided in two ways: as trigger arguments (inline key-value pairs) or via a TOML configuration file. Both approaches accept the same parameter names. The TOML approach is recommended when you have complex configs such as many feature_order tokens, extra_body entries, or multiple tag_values filters, because it is easier to read and maintain.

Option 1: Trigger arguments (inline)

Pass parameters as a comma-separated list in --trigger-arguments. Use | as a separator inside list-valued parameters (feature_order, output_fields, extra_body, tag_values):

influxdb3 create trigger \
  --database mydb \
  --path "sagemaker.py" \
  --trigger-spec "every:1m" \
  --trigger-arguments 'endpoint_name=my-endpoint,source_measurement=sensor_data,feature_order={motor_speed}|{ambient_temperature},output_fields=score=predictions[*].score' \
  sagemaker_score

Option 2: TOML configuration file

Put all parameters into a .toml file, then pass only config_file_path in the trigger arguments:

influxdb3 create trigger \
  --database mydb \
  --path "sagemaker.py" \
  --trigger-spec "every:1m" \
  --trigger-arguments 'config_file_path=sagemaker_config.toml' \
  sagemaker_score

The config_file_path value is resolved as follows: - Absolute path (e.g. /etc/plugins/sagemaker_config.toml) — used as-is. - Relative path (e.g. sagemaker_config.toml) — resolved relative to the plugin directory taken from the INFLUXDB3_PLUGIN_DIR environment variable (set by the Processing Engine), falling back to PLUGIN_DIR.

When config_file_path is provided all other trigger arguments are ignored; all parameters must be in the file.

TOML format

The TOML file uses the same parameter names as trigger arguments. The key format differences are:

Parameter	Trigger args format	TOML format
feature_order	{col1}\|{col2}\|0.0 (pipe-separated string)	feature_order = ["{col1}", "{col2}", "0.0"] (array)
output_fields	score=pred[*].score\|label=pred[*].label	output_fields = ["score=pred[*].score", "label=pred[*].label"]
extra_body	parameters.top_p=0.9\|parameters.n=3	extra_body = ["parameters.top_p=0.9", "parameters.n=3"]
batch_inference	"true" or "false" (string)	batch_inference = true (native bool)
limit	"10" (string)	limit = 10 (integer)
tag_values	sensor_id:[email protected]:prod (encoded string)	[tag_values] section (see below)

Tag filters in TOML use a dedicated section where each key maps to a list of allowed values:

[tag_values]
sensor_id = ["A1", "A2"]
env       = ["prod"]

Minimal TOML example

endpoint_name      = "my-endpoint-2025-01-15"
source_measurement = "motor_data"
region             = "eu-central-1"
interval           = "5min"
limit              = 10
content_type       = "application/json"
accept             = "application/json"
json_shape         = "instances_array"
batch_inference    = true

feature_order = ["{motor_speed}", "{ambient_temperature}", "0.0"]
output_fields = ["score=predictions[*].score"]

target_measurement = "motor_predictions"

[tag_values]
sensor_id = ["A1", "A2"]

A complete reference with examples for all supported body shapes is provided in sagemaker_config_example.toml.

Plugin metadata

This plugin includes a JSON metadata schema in its docstring that defines the supported trigger type and configuration parameters. This metadata enables the InfluxDB 3 Explorer UI to display and configure the plugin.

Required parameters

Parameter	Type	Default	Description
endpoint_name	string	required	Name of the deployed SageMaker real-time endpoint
source_measurement	string	required	InfluxDB measurement (table) the plugin reads rows from
feature_order	string / array	required	Tokens describing how to build each row’s request body. Pipe-separated string in args; TOML array. See feature_order syntax
output_fields	string / array	required	name=path pairs describing how to extract predictions from the response. Pipe-separated in args; TOML array

Request format parameters

Parameter	Type	Default	Description
content_type	string	application/json	Request body Content-Type. One of application/json, text/csv
accept	string	same as content_type	Expected response Content-Type. One of application/json, application/jsonlines, text/csv, text/plain
json_shape	string	instances_array	JSON body shape (only when content_type=application/json). See json_shape values below
extra_body	string / array	none	path=value pairs merged into the JSON body (e.g. nested LLM parameters). Pipe-separated in args; TOML array. Only with JSON content types

Inference parameters

Parameter	Type	Default	Description
interval	string	60min	Lookback window for the source query. Format: </code> where unit is s, min, h, d, w, m (months≈30d), q (quarters≈91d), y (years=365d). Examples: 5min, 1h, 30d
limit	integer	1	Maximum number of rows to read per scheduled call. String or integer accepted
batch_inference	boolean	true	If true, send all selected rows in one request and parse a batch response. If false, one request per row. String "true"/"false" (args) or native bool (TOML)
forecast_output	boolean	false	If true, output_fields paths may return arrays; each position becomes a separate output row. Scalar values are broadcast to all rows. Only supported with accept=application/json. Use with json_shape=inputs_timeseries for time-series forecasting models
region	string	eu-central-1	AWS region of the SageMaker endpoint
target_model	string	none	Optional model identifier for multi-model endpoints — sets X-Amzn-SageMaker-Target-Model header

Output parameters

Parameter	Type	Default	Description
target_measurement	string	_predictions</code>	Measurement to write predictions into
target_database	string	trigger’s database	Database to write predictions into
timestamp_path	string	none	Optional path to extract per-row timestamps from the response. JMESPath for JSON/JSONLines, integer column index for CSV. If empty, the plugin uses time.time_ns(). If set but a row’s timestamp is missing or unparseable, that prediction is skipped with an error (no wall-clock fallback)

Filtering parameters

Parameter	Type	Default	Description
tag_values	string / table	none	Tag filter applied to the source query. In args: tag1:[email protected]:val3 — dot separates tag pairs, colon separates tag name from values, @ separates multiple values. In TOML: [tag_values] section with tag = ["v1", "v2"]. Tags with a single value are also written to the output line

feature_order syntax

feature_order is a list of tokens. In trigger arguments it is pipe-separated; in TOML it is a native array. Each token is either a column reference or a literal value. Aliases (:alias) are mainly used in object-shape JSON bodies as JSON keys.

Token	Meaning
{col}	Take the value of column col from the row. In object shapes, the JSON key equals col
{col:alias}	Take the value of column col. In object shapes, the JSON key equals alias; in array/CSV shapes the alias is ignored (one warning at init)
0, 0.0, -3.14, 1e3	Numeric literal (int or float). In CSV the literal is written as text
true, false	Boolean literal (in JSON bodies)
null	JSON null
"text", 'text'	String literal
"text":alias, 0.0:alias, etc.	Literal with key alias. Required for literals in object shapes (instances_object, raw_object); ignored elsewhere with a warning

To use a literal containing : or |, wrap it in quotes: "1:30":time.

output_fields syntax

output_fields = name=path|name=path|... (args) or output_fields = ["name=path", ...] (TOML)

Each entry produces one field on the output line. The path syntax depends on accept:

accept	Path syntax	Example
application/json	JMESPath — yields an array in batch mode, scalar in per-row mode	forecasting=predictions[*].score (batch) or forecasting=score (per-row)
application/jsonlines	JMESPath, applied per line	forecasting=score
text/csv	integer column index (0-based)	forecasting=0
text/plain	empty (response body becomes value); exactly one entry	result=

In batch mode, M (the number of written rows) equals min(length) across all output_fields paths and timestamp_path. If lengths differ, the plugin truncates and logs a warning.

In forecast mode (forecast_output=true), each output_fields path may return an array — every array element becomes a separate output row. Paths that return a scalar are broadcast to all rows. All arrays must have equal length; if they differ, the min-length rule applies with a warning.

The Python type of each extracted value determines the InfluxDB field type: - int → int64_field - float → float64_field - bool → bool_field - str → string_field - list/dict → row error (use a more specific JMESPath; in forecast mode, nested arrays inside a forecast array are not supported)

json_shape values

Shape	Body produced	Used by
instances_array	{"instances": [[v1,v2,...], ...]}	TF Serving REST (positional)
instances_object	{"instances": [{"col": v, ...}, ...]}	TF Serving REST (named columns)
instances_features	{"instances": [{"features": [v1,v2,...]}, ...]}	Built-in AWS algorithms: KMeans, k-NN, RCF, Linear Learner, NTM, PCA
inputs	{"inputs": [v1,v2,...]} — single row	TF Serving simplified columnar (single tensor)
inputs_array	{"inputs": [[v1,v2], ...]}	TF Serving / PyTorch batch
inputs_flat	{"inputs": [v1,v2,...]} — one value per row, requires exactly one {col} token	Hugging Face NLP batch ({"inputs": ["text1", "text2"]})
inputs_timeseries	{"inputs": [{"target": [v1,v2,...,vN]}]} — all rows collected into one target array; requires exactly one {col} token	Time-series forecasting models (Amazon Chronos-Bolt, etc.)
raw_array	[[v1,v2,...], ...]	Custom containers, simplified TF Serving
raw_object	{"col": v, ...} — single row	Hugging Face simple, custom containers (e.g. {"inputs": "text"})

Batch compatibility: inputs and raw_object produce a single-row body and require either batch_inference=false or limit=1. All other shapes are batch-friendly.

Time-series forecasting: use inputs_timeseries together with forecast_output=true. With limit=N, all N rows from the source query are packed into a single target array and sent in one request. The response’s array fields are then expanded back into N output rows — one per forecast step.

Object shapes (instances_object, raw_object) accept literal tokens only with an alias (literal:alias); the alias becomes the JSON key.

extra_body syntax

extra_body = path=value|path=value|... (args) or extra_body = ["path=value", ...] (TOML)

Each entry adds a static value at a JSON path. Dotted paths produce nested objects; values are coerced (numbers, booleans, null, quoted strings). Array values use semicolons as element separators inside square brackets: [v1;v2;v3].

# args — scalar values
extra_body = parameters.max_new_tokens=50|parameters.top_p=0.95|parameters.do_sample=true

# args — array value (semicolons, no spaces inside brackets)
extra_body = parameters.quantile_levels=[0.1;0.5;0.9]|parameters.prediction_length=10

# TOML
extra_body = [
    "parameters.max_new_tokens=50",
    "parameters.top_p=0.95",
    "parameters.do_sample=true",
    "parameters.quantile_levels=[0.1;0.5;0.9]",
]

→ merged into the body as:

{"parameters":{"max_new_tokens":50,"top_p":0.95,"do_sample":true,"quantile_levels":[0.1,0.5,0.9]}}

Restrictions: - Cannot be used with content_type=text/csv. - Cannot be used with json_shape=raw_array (top-level list — nothing to merge into). - Conflicts with feature_order keys at any depth fail at run time.

Auto-tags

Every output line carries the following tags:

Tag	Value
sagemaker_endpoint	endpoint_name
sagemaker_source_measurement	source_measurement
sagemaker_region	region
sagemaker_model	target_model (only when set)

Single-valued tags from tag_values are also written to the output line.