FeatureService API API Reference

Tecton provides a low latency feature server that exposes HTTP endpoints to retrieve feature values and metadata from the online store. This is typically used during model predictions. The feature servers retrieve data from the online store and perform any additional aggregations and filtering as necessary.

Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0

Authentication

Tecton API Key

Use your Tecton API Key (prefixed by tecton-key ) as the Authorization request header field. E.g. for API Key secretapikey123, use tecton-key secretapikey123.

type
apiKey
name
Authorization
in
header

GetFeatures

POST /v1/feature-service/get-features

Get Features API to retrieve feature values from Tecton's online store

undefined

Request Example
{
  "params": {
    "feature_service_name": "ctr_prediction_service",
    "join_key_map": {
      "ad_id": "5417",
      "user_uuid": "6c423390-9a64-52c8-9bb3-bbb108c74198"
    }
  }
}
404 Not Found

Not Found

Response Example (200 OK)
{
  "result": {
    "features": [
      15
    ]
  }
}
Response Example (404 Not Found)
{
  "error": "Unknown feature_service_id: my_feature_service",
  "message": "Unknown feature_service_id: my_feature_service",
  "code": 5
}

Metadata

POST /v1/feature-service/metadata

Get Metadata about the feature service from Tecton

Request Example
{
  "params": {
    "feature_service_name": "ctr_prediction_service"
  }
}
404 Not Found

Not Found

Response Example (200 OK)
{
  "featureServiceType": "DEFAULT",
  "inputJoinKeys": [
    {
      "name": "adId",
      "type": "string"
    }
  ],
  "feature_values": [
    {
      "name": "ad_ground_truth_ctr_performance_7_days",
      "type": "float64"
    },
    {
      "name": "user_partner_impression_count_7_days",
      "type": "float64"
    },
    {
      "name": "user_total_ad_frequency_counts",
      "type": "int64"
    }
  ]
}
Response Example (404 Not Found)
{
  "error": "Unknown feature_service_name: my_feature_service for workspace: prod",
  "message": "Unknown feature_service_name: my_feature_service for workspace: prod",
  "code": 5
}

Schema Definitions

FeatureServerComplexDataType: object

Data Types supported by Tecton for feature values in the feature serving api.

type: FeatureServerDataType
element_type: FeatureServerComplexDataType

The data type of elements in an array. This field is only set if type == "array".

fields: FeatureServerStructField

The name and data type of the fields in a struct. Struct values will be returned the same order as this metadata with nulls for missing data. This field is only set if type == "struct".

FeatureServerStructField
Example
{
  "type": "string",
  "element_type": {
    "type": "string",
    "element_type": "#/definitions/FeatureServerComplexDataType",
    "fields": [
      {
        "name": "string",
        "data_type": "#/definitions/FeatureServerComplexDataType"
      }
    ]
  },
  "fields": [
    {
      "name": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          "#/definitions/FeatureServerStructField"
        ]
      }
    }
  ]
}

FeatureServerDataType: string

Data Types supported by Tecton for feature values in the feature serving api.

string missing_type, boolean, float64, int64, string, array, float32, struct missing_type

FeatureServerStructField: object

name: string
data_type: FeatureServerComplexDataType
Example
{
  "name": "string",
  "data_type": {
    "type": "string",
    "element_type": "#/definitions/FeatureServerComplexDataType",
    "fields": [
      {
        "name": "string",
        "data_type": "#/definitions/FeatureServerComplexDataType"
      }
    ]
  }
}

FeatureServiceLocator: object

feature_service_id: string

FeatureService ID. Exactly one of this field and feature_service_name must be set.

feature_service_name: string

FeatureService name. Exactly one of this field and feature_service_id must be set.

workspace_name: string

Workspace name.

Example
{
  "feature_service_name": "ctr_prediction_service"
}

FeatureServiceType: string

string DEFAULT, WILDCARD DEFAULT

GetFeaturesParameters: object

Parameters for get-features.

Exactly one of feature_service_name and feature_service_id must be set.

feature_service_id: string

FeatureService ID. Exactly one of this field and feature_service_name must be set.

feature_service_name: string

FeatureService name. Exactly one of this field and feature_service_id must be set.

workspace_name: string
join_key_map: object

Join keys used for table-based FeatureViews.

The key of this map is the join key name and the value is the join key value for this request. The values are encoded as follows:

  • For string keys, the value should be a string.
  • For int64 keys, the value should be a string of the decimal representation of the integer.
request_context_map: object

Request context used for OnDemand FeatureViews.

The key of this map is the request context key name and the value is the request context value for this request. The values are encoded as follows:

  • For string values, the value should be a string.
  • For int64 values, the value should be a string of the decimal representation of the integer.
  • For double values, the value should be a number.
metadata_options: MetadataOptions
allow_partial_results: boolean false

Whether incomplete results should be returned when the Online Feature Store size limit has been exceeded for this request. If this is not true, then the response will be an error in this case.

This is an advanced option and should only be set after consulting with the Tecton team.

Example
{
  "feature_service_name": "ctr_prediction_service",
  "join_key_map": {
    "ad_id": "5417",
    "user_uuid": "6c423390-9a64-52c8-9bb3-bbb108c74198"
  }
}

GetFeaturesRequest: object

Example
{
  "params": {
    "feature_service_name": "ctr_prediction_service",
    "join_key_map": {
      "ad_id": "5417",
      "user_uuid": "6c423390-9a64-52c8-9bb3-bbb108c74198"
    }
  }
}

GetFeaturesResponse: object

result: GetFeaturesResult
metadata: Metadata
Example
{
  "result": {
    "features": [
      "object"
    ],
    "join_keys": [
      "object"
    ]
  },
  "metadata": {
    "features": [
      {
        "name": "string",
        "effective_time": "string (date-time)",
        "type": "string",
        "data_type": {
          "type": "string",
          "element_type": "#/definitions/FeatureServerComplexDataType",
          "fields": [
            {
              "name": "string",
              "data_type": "#/definitions/FeatureServerComplexDataType"
            }
          ]
        }
      }
    ],
    "join_keys": [
      {
        "name": "string",
        "effective_time": "string (date-time)",
        "type": "string",
        "data_type": {
          "type": "string",
          "element_type": "#/definitions/FeatureServerComplexDataType",
          "fields": [
            {
              "name": "string",
              "data_type": "#/definitions/FeatureServerComplexDataType"
            }
          ]
        }
      }
    ],
    "slo_info": {
      "slo_eligible": "boolean",
      "slo_server_time_seconds": "number (double)",
      "slo_ineligibility_reasons": [
        "string"
      ],
      "server_time_seconds": "number (double)",
      "store_max_latency": "number (double)",
      "store_response_size_bytes": "integer (int32)"
    },
    "partial_results": "boolean"
  }
}

GetFeaturesResult: object

The result feature ordering is determined with the following rules:

  1. Within on-demand feature views, features ordering is the same as output_schema
  2. Within all other feature views, features ordering is alphabetical.
  3. Requests that return multiple feature views place on-demand features first (in alphabetical order) followed by the others (in alphabetical order). You can determine the ordering of features in a feature service by setting the include_names field in your request metadata. The feature ordering will be in the metadata.features. This ordering is stable; it will remain the same for each call.
features: object[]
object
join_keys: object[]
object
Example
{
  "features": [
    "object"
  ],
  "join_keys": [
    "object"
  ]
}

Metadata: object

Metadata served if requested when retrieving feature values from Tecton.

features: MetadataItem
MetadataItem
join_keys: MetadataItem
MetadataItem
slo_info: SloInfo
partial_results: boolean
Example
{
  "features": [
    {
      "name": "string",
      "effective_time": "string (date-time)",
      "type": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      }
    }
  ],
  "join_keys": [
    {
      "name": "string",
      "effective_time": "string (date-time)",
      "type": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      }
    }
  ],
  "slo_info": {
    "slo_eligible": "boolean",
    "slo_server_time_seconds": "number (double)",
    "slo_ineligibility_reasons": [
      "string"
    ],
    "server_time_seconds": "number (double)",
    "store_max_latency": "number (double)",
    "store_response_size_bytes": "integer (int32)"
  },
  "partial_results": "boolean"
}

MetadataItem: object

Metadata item object.

name: string
effective_time: string (date-time)

The effective serving time for this feature. This is the most recent time that's aligned to the interval for which a full aggregation is available for this feature. Passing this in the spine of an offline feature request should guarantee retrieving the same value as is in this response.

type: FeatureServerDataType
data_type: FeatureServerComplexDataType
Example
{
  "name": "string",
  "effective_time": "string (date-time)",
  "type": "string",
  "data_type": {
    "type": "string",
    "element_type": "#/definitions/FeatureServerComplexDataType",
    "fields": [
      {
        "name": "string",
        "data_type": "#/definitions/FeatureServerComplexDataType"
      }
    ]
  }
}

MetadataOptions: object

Options for retrieving additional metadata about the feature values.

include_names: boolean

Enable if you want to include feature names in the metadata response.

include_effective_times: boolean

Enable if you want effective times of the feature values in the metadata response.

include_data_types: boolean

Enable if you want data types of the features in the metadata response.

include_slo_info: boolean

Enable if you want SLO information in the response.

Example
{
  "include_names": "boolean",
  "include_effective_times": "boolean",
  "include_data_types": "boolean",
  "include_slo_info": "boolean"
}

NameAndType: object

name: string
data_type: FeatureServerComplexDataType
type: FeatureServerDataType

Deprecated. Please use data_type instead.

Example
{
  "name": "string",
  "data_type": {
    "type": "string",
    "element_type": "#/definitions/FeatureServerComplexDataType",
    "fields": [
      {
        "name": "string",
        "data_type": "#/definitions/FeatureServerComplexDataType"
      }
    ]
  },
  "type": "string"
}

ServiceMetadataRequest: object

Returns metadata about a FeatureService, including the schema for join keys and request context, as well as the in-order output schema of returned feature values.

params: FeatureServiceLocator
Example
{
  "params": {
    "feature_service_name": "ctr_prediction_service"
  }
}

ServiceMetadataResponse: object

This response describes expected inputs and outputs for GetFeaturesParameters, GetFeaturesResponse and QueryFeaturesResponse.

feature_service_type: FeatureServiceType
input_join_keys: NameAndType

The expected fields to be passed in the join_key_map parameter.

NameAndType
input_request_context_keys: NameAndType

The expected fields to be passed in the request_context_map parameter.

NameAndType
output_join_keys: NameAndType

The fields to be returned in the join_keys list in GetFeaturesResponse or QueryFeaturesResponse. Only applies if the FeatureServiceType is WILDCARD.

NameAndType
feature_values: NameAndType

The fields to be returned in the features list in GetFeaturesResponse or QueryFeaturesResponse. The order of returned features will match the order returned by GetFeaturesResponse or QueryFeaturesResponse.

NameAndType
Example
{
  "feature_service_type": "string",
  "input_join_keys": [
    {
      "name": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      },
      "type": "string"
    }
  ],
  "input_request_context_keys": [
    {
      "name": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      },
      "type": "string"
    }
  ],
  "output_join_keys": [
    {
      "name": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      },
      "type": "string"
    }
  ],
  "feature_values": [
    {
      "name": "string",
      "data_type": {
        "type": "string",
        "element_type": "#/definitions/FeatureServerComplexDataType",
        "fields": [
          {
            "name": "string",
            "data_type": "#/definitions/FeatureServerComplexDataType"
          }
        ]
      },
      "type": "string"
    }
  ]
}

SloIneligibilityReason: string

Feature Serving Response can be ineligible for SLO due to the following reasons. The reason is set with the following values as part of the response when asked for SLO Info.

string UNKNOWN, DYNAMODB_RESPONSE_SIZE_LIMIT_EXCEEDED, REDIS_RESPONSE_SIZE_LIMIT_EXCEEDED, REDIS_LATENCY_LIMIT_EXCEEDED UNKNOWN

SloInfo: object

SLO Info provided by Tecton when serving feature values. This can help you better understand SLO provided by Tecton.

slo_eligible: boolean

If the response was eligible for SLO.

slo_server_time_seconds: number (double)

The server time minus any time spent waiting on line transforms to finish after all table transforms have finished. This is the indicator used for determining whether we are meeting the SLO.

slo_ineligibility_reasons: SloIneligibilityReason

Reasons for the response not being eligible for SLO.

SloIneligibilityReason
server_time_seconds: number (double)

This includes the total time spent in the feature server including online transforms and store latency.

store_max_latency: number (double)

Max latency observed by the request from the store in seconds. Tecton fetches multiple feature views in parallel.

store_response_size_bytes: integer (int32)

Total store response size bytes.

Example
{
  "slo_eligible": "boolean",
  "slo_server_time_seconds": "number (double)",
  "slo_ineligibility_reasons": [
    "string"
  ],
  "server_time_seconds": "number (double)",
  "store_max_latency": "number (double)",
  "store_response_size_bytes": "integer (int32)"
}