Chalk home page
Docs
API
CLI
  1. Online Queries
  2. Overview

Chalk maintains several client libraries and a REST API for fetching feature values.

​
Library support

Chalk maintains libraries in several major languages for fetching online feature values. If you need support for a language that we don’t support, let us know! We also support a rest API if you’d like to build your own.

Client libraries

Query for features in your favorite language.

> chalk query \
      --in user.id=1 \
      --out user.identity.is_voip_phone \
      --out user.fraud_score \
      --staleness user.account_balance=10m \
      --environment staging \
      --tag live

​
REST API

Chalk supports a REST API for querying online features and exposes this endpoint in several API clients. When you execute an online query, resolvers will execute to produce the requested data. Online query will prioritize running online resolvers over offline resolvers to compute features if both are possible.

The following endpoint can also be hit with the python ChalkClient by using its query method. For information on how to authenticate the ChalkClient, check out the section on authentication. Read more about the parameters to this method here.

​
Request

POST
https://api.chalk.ai/v1/query/online
Attributes
inputsmap[string, JSON]
Input features and values are provided at the time of request. For example, primary key-value pairs often designate the subset of data returned. Feature inputs are provided by fully qualified path, rooted in the same feature namespace. Has many featuresare input as lists, and struct features are input as Json.

An example of passing a user with two credit cards as input: {user.id: '1', user.cards: [card.id: 'xyz', card.id:'abc']}

outputsstring[]
Outputs are the features that you'd like to compute from the inputs.
stalenessmap[string, duration]
Maximum staleness overrides for any output features or intermediate features. See query caching for more information.
contextQueryContext?
The context object controls the environment and tags under which a request should execute resolvers:
QueryContext
environmentstring?
The environment in which to run the resolvers. Like resolvers, API tokens can be scoped to an environment. If no environment is specified in the query, but the token supports only a single environment, then that environment will be taken as the scope for executing the request.
tagsstring[]?
The tags used to scope the resolvers.
preview_deployment_idstring?
The preview deployment id. See Preview Deployments for more information.
query_namestring?
The query name. Information about Named Queries is available in the dashboard.
branchstring?
If specified, routes to the relevant branch. See Branches for more information.

More information on parameters is available here

​
Response

Attributes
dataFeatureResult[]
The outputs features and any query metadata
FeatureResult
fieldstring
The name of the feature requested, eg. user.identity.has_voip_phone.
valuetypeof(field)?
The value of the requested feature. If an error was encountered in resolving this feature, this field will be empty.
errorChalkError?
The error code encountered in resolving this feature. If no error occurred, this field is empty.
metaFeatureResolutionMeta?
Metadata pertaining to the feature, including the resolver run and whether the result was a cache hit.
errorsChalkError[]?
Errors encountered while running the resolvers. Each element in the list is a ChalkError. If no errors were encountered, this field is empty.
metaQueryMeta?
Metadata related to the query. Returned if include_meta or explain is set to True.
QueryMeta
execution_duration_sfloat
The time, expressed in seconds, that Chalk spent executing this query.
deployment_idstring?
The id of the deployment that served this query.
environment_idstring?
The id of the environment that served this query.
environment_namestring?
The short name of the environment that served this query. For example: "dev" or "prod".
query_idstring?
A unique ID generated and persisted by Chalk for this query. All computed features, metrics, and logs are associated with this ID. Your system can store this ID for audit and debugging workflows.
query_timestampdatetime?
At the start of query execution, Chalk computes 'datetime.now()'. This value is used to timestamp computed features.
query_hashstring?
Deterministic hash of the 'structure' of the query. Queries that have the same input/output features will typically have the same hash; changes may be observed over time as we adjust implementation details.
explain_outputstring?
An unstructured string containing diagnostic information about the query execution. Only included ifexplain is set toTrue.

​
Query Explanation

Chalk offers support for the user for when queries don’t work. The first step is always to check to see the response contains any errors. Often, the error message will directly point to the failure.

In the case of more complicated queries, queries can be sent with explain=True. This will return a representation of the query plan in the meta return attribute. The user can use this information to verify the resolvers and operators ran during execution. Beware, this will result in slower execution times.

Some queries that involve multiple operations might need additional tracking. Users can supply store_plan_stages=True to store intermediate outputs at all operations of the query. This will dramatically slow things down, so use wisely! These results are visible in the dashboard under the “Queries” page.

For more information, read the ChalkClient docs here.