chalk

package module
v0.4.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2024 License: Apache-2.0 Imports: 18 Imported by: 0

README

Go Reference Test

Go Chalk

The official Chalk client library.

Usage

Requirements
  • Go 1.19 or later
Installation

Make sure your project is using Go Modules (it will have a go.mod file in its root if it already is):

go mod init

Then, reference chalk-go in a Go program with import:

import (
    "github.com/chalk-ai/chalk-go"
)

Run any of the normal go commands (build/install/test). The Go toolchain will resolve and fetch the chalk-go module automatically.

Alternatively, you can also explicitly go get the package into a project:

go get -u github.com/chalk-ai/chalk-go
Codegen

Chalk generates Go structs from your python feature definitions, which makes it easy to use your features from Go.

Run the code-gen command inside your chalk project to generate a file containing your generated structs, then copy that file into your go project.

chalk codegen go --out=<OUTPUT_FILEPATH>
Connect to chalk

Create a client using the NewClient method. The returned client gets its configuration:

  1. From overrides configured by passing in a *chalk.ClientConfig
  2. From environment variables if no arguments are passed
  3. From a ~/.chalk.yml file if neither 1 nor 2 are available

(2) and (3) are applicable only for these options.

Without overrides
import (
    "github.com/chalk-ai/chalk-go"
)

client := chalk.NewClient()
With overrides
client, err := chalk.NewClient(&chalk.ClientConfig{
    ClientId:      "id-89140a6614886982a6782106759e30",
    ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
    ApiServer:     "https://api.chalk.ai",
    EnvironmentId: "qa",
    Branch:        "jorges-december",
})
Online Query

Query online features using the generated feature structs. Access the results in the returned object or by passing the address of a variable with the correct type.

user := User{}
_, err = client.OnlineQuery(
    chalk.OnlineQueryParams{}.
        WithInput(Features.User.Id, "<INPUT_VALUE>").
        WithOutputs(Features.User.Id, Features.User.LastName),
    &user,
)
Offline Query

When executing an offline query, a dataset is returned and can be downloaded as parquet files using the DownloadData method.

res, _ := client.OfflineQuery(
    chalk.OfflineQueryParams{}.
        WithInput(Features.User.Id, []any{...}).
        WithOutputs(Features.User),
)

err = res.Revisions[0].DownloadData(<FILE_DIRECTORY>)
Upload Features

Chalk allows you to synchronously persist features directly to your online and offline stores.

res, err := client.UploadFeatures(
    chalk.UploadFeaturesParams{
        Inputs: map[any]any{
            Features.User.Id: []string{"user-1", "user-2"},
            "user.last_name": []string{"Borges", "Paris"},
        },
    },
)
Querying against a branch

To query against a branch, create a ChalkClient with a Branch specified, and then make queries using that client.

client, err := chalk.NewClient(&chalk.ClientConfig{
    Branch:        "jorges-december",
})
Configuring Logging

By default, Chalk logs error messages only (which are sent to stderr). Configure default logging using the global DefaultLeveledLogger variable:

chalk.DefaultLeveledLogger = &chalk.StdOutLeveledLogger{
    Level: chalk.LevelInfo,
}

It's possible to use non-Chalk leveled loggers as well. Chalk expects loggers to comply to the following interface:

type LeveledLogger interface {
    Debugf(format string, v ...interface{})
    Errorf(format string, v ...interface{})
    Infof(format string, v ...interface{})
    Warnf(format string, v ...interface{})
}

Some loggers like Logrus and Zap's SugaredLogger support this interface natively, so it's possible to set DefaultLeveledLogger to a *logrus.Logger or *zap.SugaredLogger directly. To use other loggers, you may need a shim layer.

Contributing

We'd love to accept your patches! If you submit a pull request, please keep the following guidelines in mind:

  1. Fork the repo, develop and test your code changes.
  2. Ensure your code adheres to the existing style.
  3. Ensure that your code has an appropriate set of tests that pass.
  4. Submit a pull request.
Development

Clone the git repo from github.com/chalk-ai/chalk-go.

  1. All patches must be go fmt compatible.
  2. All types, structs, and functions should be documented.
Testing

To execute the tests: go test ./.... Enure all tests pass

License

Apache 2.0 - See LICENSE for more information.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Request errors are raised before execution of your
	// resolver code. They may occur due to invalid feature
	// names in the input or a request that cannot be satisfied
	// by the resolvers you have defined.
	Request = ErrorCodeCategory{"REQUEST"}

	// Field errors are raised while running a feature resolver
	// for a particular field. For this type of error, you'll
	// find a feature and resolver attribute in the error type.
	// When a feature resolver crashes, you will receive null
	// value in the response. To differentiate from a resolver
	// returning a null value and a failure in the resolver,
	// you need to check the error schema.
	Field = ErrorCodeCategory{"FIELD"}

	// Network errors are thrown outside your resolvers.
	// For example, your request was unauthenticated,
	// connection failed, or an error occurred within Chalk.
	Network = ErrorCodeCategory{"NETWORK"}
)
View Source 
var (
	// ParseFailed indicates the query contained features that do not exist.
	ParseFailed = ErrorCode{Value: "PARSE_FAILED"}

	// ResolverNotFound indicates a resolver was required as part of running the dependency graph that could not be found.
	ResolverNotFound = ErrorCode{"RESOLVER_NOT_FOUND"}

	// InvalidQuery indicates the query is invalid. All supplied features need to be rooted in the same top-level entity.
	InvalidQuery = ErrorCode{"INVALID_QUERY"}

	// ValidationFailed indicates a feature value did not match the expected schema (e.g. `incompatible type "int"; expected "str"`)
	ValidationFailed = ErrorCode{"VALIDATION_FAILED"}

	// ResolverFailed indicates the resolver for a feature errored.
	ResolverFailed = ErrorCode{"RESOLVER_FAILED"}

	// ResolverTimedOut indicates the resolver for a feature timed out.
	ResolverTimedOut = ErrorCode{"RESOLVER_TIMED_OUT"}

	// UpstreamFailed indicates a crash in a resolver that was to produce an input for the resolver crashed, and so the resolver could not run.
	UpstreamFailed = ErrorCode{"UPSTREAM_FAILED"}

	// Unauthenticated indicates the request was submitted with an invalid authentication header.
	Unauthenticated = ErrorCode{"UNAUTHENTICATED"}

	// Unauthorized indicates the supplied credentials do not provide the right authorization to execute the request.
	Unauthorized = ErrorCode{"UNAUTHORIZED"}

	// InternalServerError indicates an unspecified error occurred.
	InternalServerError = ErrorCode{"INTERNAL_SERVER_ERROR"}

	// Cancelled indicates the operation was cancelled, typically by the caller.
	Cancelled = ErrorCode{"CANCELLED"}

	// DeadlineExceeded indicates the deadline expired before the operation could complete.
	DeadlineExceeded = ErrorCode{"DEADLINE_EXCEEDED"}
)
View Source 
var FieldNotFoundError = errors.New("field not found")

Functions

func DesuffixFqn 

func DesuffixFqn(fqn string) string

func InitFeatures 

func InitFeatures[T any](t *T) error

Types

type BuilderError added in v0.3.2 

type BuilderError struct {
	Err       error
	Type      BuilderErrorType
	ParamType ParamType
	Feature   any
	Value     any
}

func (*BuilderError) Error added in v0.3.2 

func (e *BuilderError) Error() string

type BuilderErrorType added in v0.3.2 

type BuilderErrorType int
const (
	BuilderErrorUnknown BuilderErrorType = iota
	InvalidFeatureType
	UnwrapFeatureError
	InvalidRequest
)

type BuilderErrors added in v0.3.2 

type BuilderErrors []*BuilderError

func (BuilderErrors) Error added in v0.3.2 

func (e BuilderErrors) Error() string

type Client 

type Client interface {
	// OnlineQuery computes features values using online resolvers.
	// See [query basics] for more information.
	//
	// resultHolder is a pointer to the struct that the result should be
	// unmarshalled into. The struct passed in should be the struct that
	// represents the feature set corresponding to the root output namespace.
	// For instance, in the example below, 'user' is the root output
	// namespace, so a pointer to a 'User' struct is passed in.
	// You can also choose to pass 'nil' as the resultHolder, in which case
	// you should use OnlineQueryResult.UnmarshalInto to populate a struct.
	//
	// The Chalk CLI can codegen structs for all available features with
	// the [chalk codegen] command.
	//
	// Example:
	//
	//		user := User{}
	//		res, err := client.OnlineQuery(
	//			OnlineQueryParams{
	//				IncludeMeta: true,
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//			WithInput(Features.User.Card.Id, 4).
	//			WithOutputs(Features.User.Email, Features.User.Card.Id),
	//			&user,
	//		)
	//		fmt.Println("User email: ", user.Email)
	//		fmt.Println("User card ID: ", user.Card.Id)
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	// [query basics]: https://docs.chalk.ai/docs/query-basics
	OnlineQuery(args OnlineQueryParamsComplete, resultHolder any) (OnlineQueryResult, error)

	// OnlineQueryBulk computes features values using online resolvers,
	// and has the ability to query multiple primary keys at once.
	// OnlineQueryBulk also has the ability to return a has-many feature
	// in the form of an arrow.Record. The usual features are returned
	// in bulk in an arrow.Record too, with each column name corresponding
	// to the feature name.
	//
	// The Chalk CLI can codegen structs for all available features with
	// the [chalk codegen] command.
	//
	// Example:
	//
	// import "github.com/apache/arrow/go/v16/arrow/array"
	//
	//
	//		res, err := client.OnlineQueryBulk(
	//			OnlineQueryParams{
	//				IncludeMeta: true,
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//			WithInput("user.id", []int{1, 2, 3, 4}).
	//			WithOutputs("user.email", "user.transactions"),
	//		)
	//		defer res.Release()
	//
	//		reader := array.NewTableReader(res.ScalarsTable, 10_000)
	//		defer reader.Release()
	//		for reader.Next() {
	//		    record := reader.Record()
	//		    // Do something with the record
	//		}
	//
	//		txnTable := res.GroupsTables["user.transactions"]
	//		txnReader := array.NewTableReader(txnTable, 10_000)
	//		// Do something with the txnReader
	//		defer txnReader.Release()
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	// [query basics]: https://docs.chalk.ai/docs/query-basics
	OnlineQueryBulk(args OnlineQueryParamsComplete) (OnlineQueryBulkResult, error)

	// UploadFeatures synchronously persists feature values to the online store and
	// offline store. The `Inputs` parameter should be a map of features to values.
	// The features should either be a string or codegen-ed Feature object. The values
	// should be a slice of the appropriate type. All slices should be the same length
	// as the number of entities you want to upload features for.
	//
	// The upload is successful if the response contains no errors.
	//
	// Example:
	//
	// 		res, err := client.UploadFeatures(
	// 			UploadFeaturesParams{
	// 				Inputs: map[any]any{
	// 					Features.User.Card.Id: []string{"5555-5555-5555-5555", "4444-4444-4444-4444"},
	// 				    "new_user_model.card_id": []string{"5555-5555-5555-5555", "4444-4444-4444-4444"},
	//					"new_user_model.email": []string{"borges@chalk.ai", "jorge@chalk.ai"},
	// 				},
	//              BranchOverride: "jorge-december",
	// 			}
	// 		)
	//      if err != nil {
	//          return err.Error()
	//      }
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	UploadFeatures(args UploadFeaturesParams) (UploadFeaturesResult, error)

	// OfflineQuery queries feature values from the offline store.
	// See Dataset for more information.
	//
	// Example:
	//
	//		client.OfflineQuery(
	//			OfflineQueryParams{
	//				EnvironmentId: "pipkjlfc3gtmn",
	//			}.
	//	 		WithRequiredOutputs(Features.User.Email, Features.User.Card.Id),
	//		)
	//
	OfflineQuery(args OfflineQueryParamsComplete) (Dataset, error)

	// TriggerResolverRun triggers an offline resolver to run.
	// See https://docs.chalk.ai/docs/runs for more information.
	TriggerResolverRun(args TriggerResolverRunParams) (TriggerResolverRunResult, error)

	// GetRunStatus retrieves the status of an offline resolver run.
	// See https://docs.chalk.ai/docs/runs for more information.
	GetRunStatus(args GetRunStatusParams) (GetRunStatusResult, error)
}

Client is the primary interface for interacting with Chalk. You can use it to query data, trigger resolver runs, gather offline data, and more.

func NewClient 

func NewClient(config ...*ClientConfig) (Client, error)

NewClient creates a Client with authentication settings configured. These settings can be overriden by passing in a ClientConfig object. Otherwise, for each configuration variable, NewClient uses its corresponding environment variable if it exists. The environment variables that NewClient looks for are: 

CHALK_ACTIVE_ENVIRONMENT
CHALK_API_SERVER
CHALK_CLIENT_ID
CHALK_CLIENT_SECRET

For each config variable, if it is still not found, NewClient will look for a `~/.chalk.yml` file, which is updated when you run chalk login. If a configuration for the specific project directory if found, that configuration will be used. Otherwise, the configuration under the key `default` will be used.

Example: 

     chalkClient, chalkClientErr := chalk.NewClient(&chalk.ClientConfig{
	        ClientId:      "id-89140a6614886982a6782106759e30",
	        ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
	        ApiServer:     "https://api.chalk.ai",
	        EnvironmentId: "qa",
	        Branch:        "jorges-december",
})

type ClientConfig 

type ClientConfig struct {
	ClientId      string
	ClientSecret  string
	ApiServer     string
	EnvironmentId string

	// If specified, Chalk will route all requests from this client
	// instance to the relevant branch.
	Branch string

	// Logger is the logger that the backend will use to log errors,
	// warnings, and informational messages.
	//
	// LeveledLogger is implemented by StdOutLeveledLogger, and one can be
	// initialized at the desired level of logging.  LeveledLogger
	// also provides out-of-the-box compatibility with a Logrus Logger, but may
	// require a thin shim for use with other logging libraries that use less
	// standard conventions like Zap.
	//
	// Defaults to DefaultLeveledLogger.
	//
	// To set a logger that logs nothing, set this to a chalk.LeveledLogger
	// with a Level of LevelNull (simply setting this field to nil will not
	// work).
	Logger LeveledLogger

	// HTTPClient is an HTTP client instance to use when making API requests.
	//
	// If left unset, it'll be set to a default HTTP client for the package.
	HTTPClient HTTPClient
}

type ClientError 

type ClientError struct {
	Message string
}

ClientError is an error that occurred in Client or its dependencies.

func UnmarshalInto added in v0.3.6 

func UnmarshalInto(resultHolder any, fqnToValueMap map[Fqn]any, expectedOutputs []string) (returnErr *ClientError)

func (*ClientError) Error 

func (e *ClientError) Error() string

type ColumnMetadata 

type ColumnMetadata struct {
	FeatureFqn string `json:"feature_fqn"`
	ColumnName string `json:"column_name"`
	Dtype      string `json:"dtype"`
}

type Dataset 

type Dataset struct {
	// Whether the export job is finished (it runs asynchronously)
	IsFinished bool `json:"is_finished"`

	// Version number representing the format of the data. The client
	// uses this version number to properly decode and load the query
	// results into DataFrames.
	Version     int               `json:"version"`
	DatasetId   *string           `json:"dataset_id"`
	DatasetName *string           `json:"dataset_name"`
	Revisions   []DatasetRevision `json:"revisions"`
	Errors      []ServerError     `json:"errors"`
}

type DatasetFilter 

type DatasetFilter struct {
	SampleFilters DatasetSampleFilter `json:"sample_filters"`
	MaxCacheAge   *float64            `json:"max_cache_age_secs"`
}

type DatasetRevision 

type DatasetRevision struct {
	// UUID for the revision job.
	RevisionId string `json:"revision_id"`

	// UUID for the creator of the job.
	CreatorId string `json:"creator_id"`

	// Output features for the dataset revision.
	Outputs []string `json:"outputs"`

	// Location of the givens stored for the dataset.
	GivensUri *string `json:"givens_uri"`

	// Status of the revision job.
	Status QueryStatus `json:"status"`

	// Filters performed on the dataset.
	Filters DatasetFilter `json:"filters"`

	// Number of partitions for revision job.
	NumPartitions int `json:"num_partitions"`

	// Location of the outputs stored fo the dataset.
	OutputUris string `json:"output_uris"`

	// Storage version of the outputs.
	OutputVersion int `json:"output_version"`

	// Number of bytes of the output, updated upon success.
	NumBytes *int `json:"num_bytes"`

	// Timestamp for creation of revision job.
	CreatedAt *time.Time `json:"created_at"`

	// Timestamp for start of revision job.
	StartedAt *string `json:"started_at"`

	// Timestamp for end of revision job.
	TerminatedAt *time.Time `json:"terminated_at"`

	// Name of revision, if given.
	DatasetName *string `json:"dataset_name"`

	// ID of revision, if name is given.
	DatasetId *string `json:"dataset_id"`
	// contains filtered or unexported fields
}

func (*DatasetRevision) DownloadData 

func (d *DatasetRevision) DownloadData(directory string) error

DownloadData downloads output files pertaining to the revision to given path. Datasets are stored in Chalk as sharded Parquet files. With this method, you can download those raw files into a directory for processing with other tools.

type DatasetSampleFilter 

type DatasetSampleFilter struct {
	LowerBound *time.Time
	UpperBound *time.Time
	MaxSamples *int
}

type ErrorCode 

type ErrorCode struct {
	Value string
}

ErrorCode indicates the type of error occurred

func (*ErrorCode) UnmarshalJSON 

func (e *ErrorCode) UnmarshalJSON(data []byte) error

type ErrorCodeCategory 

type ErrorCodeCategory struct {
	Value string
}

func (*ErrorCodeCategory) UnmarshalJSON 

func (c *ErrorCodeCategory) UnmarshalJSON(data []byte) error

type ErrorResponse 

type ErrorResponse struct {
	// Errors that occurred in Chalk's server.
	ServerErrors []ServerError

	// Errors that occurred in Client or its dependencies.
	ClientError *ClientError

	// Errors that are standard HTTP errors such as missing authorization.
	HttpError *HTTPError
}

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

type Feature 

type Feature struct {
	Fqn string
}

func UnwrapFeature 

func UnwrapFeature(t any) (result *Feature, returnErr error)

type FeatureResolutionMeta 

type FeatureResolutionMeta struct {
	// The name of the resolver that computed the feature value.
	ChosenResolverFqn string `json:"chosen_resolver_fqn"`

	// Whether the feature request was satisfied by a cached value.
	CacheHit bool `json:"cache_hit"`

	// Primitive type name for the feature, e.g. `str` for `some_feature: str`.
	// Returned only if query-level 'include_meta' is True.
	PrimitiveType string `json:"primitive_type"`

	// The version that was selected for this feature. Defaults to `default_version`, if query
	// does not specify a constraint. If no versioning information is provided on the feature definition,
	// the default version is `1`.
	Version int `json:"version"`
}

type FeatureResult 

type FeatureResult struct {
	// The name of the feature requested, e.g. 'user.identity.has_voip_phone'.
	Field string

	// The value of the requested feature.
	// If an error was encountered in resolving this feature,
	// this field will be empty.
	Value any

	// The primary key of the resolved feature.
	Pkey any

	// The time at which this feature was computed.
	// This value could be significantly in the past if you're using caching.
	Timestamp time.Time

	// Detailed information about how this feature was computed.
	Meta *FeatureResolutionMeta

	// The error encountered in resolving this feature.
	// If no error occurred, this field is empty.
	Error *ServerError
}

type Fqn added in v0.3.6 

type Fqn = string

type GetOfflineQueryJobResponse 

type GetOfflineQueryJobResponse struct {
	IsFinished bool             `json:"is_finished"`
	Version    int              `json:"version"`
	Urls       []string         `json:"urls"`
	Errors     []ServerError    `json:"errors"`
	Columns    []ColumnMetadata `json:"columns"`
}

type GetRunStatusParams 

type GetRunStatusParams struct {
	// RunId is the ID of the resolver run to check.
	RunId string `json:"resolver_fqn"`

	// PreviewDeploymentId, if specified, will be used by Chalk to route
	// your request to the relevant preview deployment.
	PreviewDeploymentId string `json:"preview_deployment_id"`
}

type GetRunStatusResult 

type GetRunStatusResult struct {
	// Id is the ID of the resolver run.
	Id string `json:"id"`

	// Status is the current status of the resolver run.
	Status string `json:"status"`
}

type HTTPClient added in v0.3.8 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
	Get(url string) (resp *http.Response, err error)
}

type HTTPError 

type HTTPError struct {
	// The URL of the HTTP request made.
	Path string

	// The message describing the error.
	Message string

	// HTTP status code of the error.
	StatusCode int

	// The size of the message body, in bytes.
	ContentLength int64

	// A Chalk Trace ID, useful for when contacting Chalk Support.
	Trace *string
}

HTTPError is a wrapper around a standard HTTP error such as missing authorization.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type Level 

type Level uint32

Level represents a logging level. 

const (
	// LevelNull sets a logger to show no messages at all.
	LevelNull Level = 0

	// LevelError sets a logger to show error messages only.
	LevelError Level = 1

	// LevelWarn sets a logger to show warning messages or anything more
	// severe.
	LevelWarn Level = 2

	// LevelInfo sets a logger to show informational messages or anything more
	// severe.
	LevelInfo Level = 3

	// LevelDebug sets a logger to show informational messages or anything more
	// severe.
	LevelDebug Level = 4
)

type LeveledLogger 

type LeveledLogger interface {
	// Debugf logs a debug message using Printf conventions.
	Debugf(format string, v ...interface{})

	// Errorf logs a warning message using Printf conventions.
	Errorf(format string, v ...interface{})

	// Infof logs an informational message using Printf conventions.
	Infof(format string, v ...interface{})

	// Warnf logs a warning message using Printf conventions.
	Warnf(format string, v ...interface{})
}

LeveledLogger provides a basic leveled logging interface for printing debug, informational, warning, and error messages.

It's implemented by StdOutLeveledLogger and also provides out-of-the-box compatibility with a Logrus Logger, but may require a thin shim for use with other logging libraries that you use less standard conventions like Zap. 

var DefaultLeveledLogger LeveledLogger = &StdOutLeveledLogger{
	Level: LevelError,
}

DefaultLeveledLogger is the default logger that the library will use to log errors, warnings, and informational messages.

LeveledLogger is implemented by StdOutLeveledLogger, and one can be initialized at the desired level of logging. LeveledLogger also provides out-of-the-box compatibility with a Logrus Logger, but may require a thin shim for use with other logging libraries that use less standard conventions like Zap.

This Logger will be inherited by any backends created by default, but will be overridden if a backend is created with GetBackendWithConfig with a custom StdOutLeveledLogger set.

type OfflineQueryParams 

type OfflineQueryParams struct {

	// The environment under which to run the 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.
	EnvironmentId string

	// A unique name that if provided will be used to generate and
	// save a Dataset constructed from the list of features computed
	// from the inputs.
	DatasetName string

	// The branch under which to run the resolvers.
	Branch string

	// The maximum number of samples to include in the `DataFrame`.
	MaxSamples *int

	// DefaultTime indicates the default time at which you would like to observe the features.
	// If not specified, the current time will be used as the default observation time.
	// The default observation time will be used when:
	// 1. A feature value is passed into [OfflineQueryParams.WithInput] as a [TsFeatureValue] with a nil time.
	// 2. A feature value is passed into [OfflineQueryParams.WithInput] as a raw value (not a [TsFeatureValue]).
	// For more information about observation time, see https://docs.chalk.ai/docs/temporal-consistency
	DefaultTime *time.Time
	// contains filtered or unexported fields
}

OfflineQueryParams defines the parameters that help you execute an online query. OfflineQueryParams is the starting point of the method chain that can help you obtain an object of type OfflineQueryParamsComplete that you can pass into Client.OfflineQuery.

func (OfflineQueryParams) MarshalJSON 

func (p OfflineQueryParams) MarshalJSON() ([]byte, error)

func (OfflineQueryParams) WithInput 

func (p OfflineQueryParams) WithInput(feature any, values []any) offlineQueryParamsWithInputs

WithInput returns a copy of Offline Query parameters with the specified inputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples. The "values" argument can contain a raw value (int or string), or it can also contain a TsFeatureValue if you want to query with a specific observation time. The observation time for raw values will be the default observation time specified as [OfflineQueryParams.DefaultTime]. If no default observation time is specified, the current time will be used. For more information about observation time, see Temporal Consistency.

func (OfflineQueryParams) WithOutputs 

func (p OfflineQueryParams) WithOutputs(features ...any) OfflineQueryParamsComplete

WithOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParams) WithRequiredOutputs 

func (p OfflineQueryParams) WithRequiredOutputs(features ...any) OfflineQueryParamsComplete

WithRequiredOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

type OfflineQueryParamsComplete 

type OfflineQueryParamsComplete struct {
	// contains filtered or unexported fields
}

OfflineQueryParamsComplete is the only type of object accepted as an argument to Client.OfflineQuery. OfflineQueryParamsComplete is obtained by calling a chain of methods starting with any method of OfflineQueryParams.

Example: 

     defaultObservedAt := time.Now().Add(-time.Hour)
		observedAt, _ := time.Parse(time.RFC822, "02 Jan 22 15:04 PST")
		client.OfflineQuery(
			OfflineQueryParams{
				EnvironmentId: "pipkjlfc3gtmn",
			}.
	 		WithInput(Features.User.Id, []any{1, chalk.TsFeatureValue{Value: 2, ObservationTime: &observedAt}}).
	 		WithRequiredOutputs(Features.User.Email, Features.User.Card.Id),
		)

It is mandatory to call [OfflineQueryParams.WithOutput] or OfflineQueryParams.WithRequiredOutputs at least once for OfflineQueryParamsComplete to be returned. Otherwise, an incomplete type will be returned, and it cannot be passed into Client.OfflineQuery.

func (OfflineQueryParamsComplete) WithInput 

func (p OfflineQueryParamsComplete) WithInput(feature any, values []any) OfflineQueryParamsComplete

WithInput returns a copy of Offline Query parameters with the specified input added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithOutputs 

func (p OfflineQueryParamsComplete) WithOutputs(features ...any) OfflineQueryParamsComplete

WithOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

func (OfflineQueryParamsComplete) WithRequiredOutputs 

func (p OfflineQueryParamsComplete) WithRequiredOutputs(features ...any) OfflineQueryParamsComplete

WithRequiredOutputs returns a copy of Offline Query parameters with the specified outputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples.

type OnlineQueryBulkResponse added in v0.3.6 

type OnlineQueryBulkResponse struct {
	QueryResults map[QueryName]onlineQueryResultFeather
}

func (*OnlineQueryBulkResponse) Unmarshal added in v0.3.6 

func (r *OnlineQueryBulkResponse) Unmarshal(body []byte) error

type OnlineQueryBulkResult added in v0.3.6 

type OnlineQueryBulkResult struct {
	// ScalarsTable is an Arrow Table containing
	// scalar features of the target feature class.
	ScalarsTable arrow.Table

	// GroupsTables is a map from a has-many feature to its
	// corresponding Arrow Table.
	GroupsTables map[string]arrow.Table

	// Execution metadata for the query. See QueryMeta for details.
	Meta *QueryMeta
}

OnlineQueryBulkResult holds the result of a bulk online query.

func (OnlineQueryBulkResult) Release added in v0.3.7 

func (r OnlineQueryBulkResult) Release()

type OnlineQueryParams 

type OnlineQueryParams struct {

	// If true, returns metadata about the query execution in the response.
	IncludeMeta bool

	// If true, returns performance metrics about the query execution in the response.
	IncludeMetrics bool

	// The environment under which to run the 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.
	EnvironmentId string

	// The tags used to scope the resolvers.
	Tags []string

	// If specified, Chalk will route your request to the relevant preview deployment.
	PreviewDeploymentId string

	// The name for class of query you're making, for example, "loan_application_model".
	QueryName string

	// A globally unique ID for the query, used alongside logs and available in web
	// interfaces. If None, a correlation ID will be generated for you and returned on
	// the response.
	CorrelationId string

	// Arbitrary key:value pairs to associate with a query.
	Meta map[string]string

	// The branch id
	BranchId *string
	// contains filtered or unexported fields
}

OnlineQueryParams defines the parameters that help you execute an online query. OnlineQueryParams is the starting point of the method chain that can help you obtain an object of type OnlineQueryParamsComplete that you can pass into Client.OnlineQuery.

func (OnlineQueryParams) WithBranchId added in v0.4.7 

func (p OnlineQueryParams) WithBranchId(branchId string) OnlineQueryParams

func (OnlineQueryParams) WithInput 

func (p OnlineQueryParams) WithInput(feature any, value any) onlineQueryParamsWithInputs

WithInput returns a copy of Online Query parameters with the specified inputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithOutputs 

func (p OnlineQueryParams) WithOutputs(features ...any) onlineQueryParamsWithOutputs

WithOutputs returns a copy of Online Query parameters with the specified outputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithStaleness 

func (p OnlineQueryParams) WithStaleness(feature any, duration time.Duration) OnlineQueryParams

WithStaleness returns a copy of Online Query parameters with the specified staleness added. For use via method chaining. See OnlineQueryParamsComplete for usage examples. See https://docs.chalk.ai/docs/query-caching for more information on staleness.

type OnlineQueryParamsComplete 

type OnlineQueryParamsComplete struct {
	// contains filtered or unexported fields
}

OnlineQueryParamsComplete is the only type of object accepted as an argument to Client.OnlineQuery. OnlineQueryParamsComplete is obtained by calling a chain of methods starting with any method of OnlineQueryParams.

Example: 

	client.OnlineQuery(
		OnlineQueryParams{
			IncludeMeta: true,
			EnvironmentId: "pipkjlfc3gtmn",
		}.
 		WithInput(Features.User.Card.Id, 4).
 		WithOutputs(Features.User.Email, Features.User.Card.Id),
	)

OnlineQueryParams.WithInput and OnlineQueryParams.WithOutputs are mandatory methods. This means they must each be called at least once for OnlineQueryParamsComplete to be returned. Otherwise, an incomplete type will be returned, and it cannot be passed into Client.OnlineQuery.

func (OnlineQueryParamsComplete) ToBytes added in v0.4.3 

func (p OnlineQueryParamsComplete) ToBytes() ([]byte, error)

func (OnlineQueryParamsComplete) WithBranchId added in v0.4.7 

func (p OnlineQueryParamsComplete) WithBranchId(branchId string) OnlineQueryParamsComplete

func (OnlineQueryParamsComplete) WithInput 

func (p OnlineQueryParamsComplete) WithInput(feature any, value any) OnlineQueryParamsComplete

WithInput returns a copy of Online Query parameters with the specified input added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithOutputs 

func (p OnlineQueryParamsComplete) WithOutputs(features ...any) OnlineQueryParamsComplete

WithOutputs returns a copy of Online Query parameters with the specified outputs added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParamsComplete) WithStaleness 

func (p OnlineQueryParamsComplete) WithStaleness(feature any, duration time.Duration) OnlineQueryParamsComplete

WithStaleness returns a copy of Online Query parameters with the specified staleness added. For use via method chaining. See OnlineQueryParamsComplete for usage examples. See https://docs.chalk.ai/docs/query-caching for more information on staleness.

type OnlineQueryResult 

type OnlineQueryResult struct {
	// The output features and any query metadata.
	Data []FeatureResult

	// Execution metadata for the query. See QueryMeta for details.
	Meta *QueryMeta
	// contains filtered or unexported fields
}

OnlineQueryResult holds the result of an online query.

func (*OnlineQueryResult) GetFeature 

func (result *OnlineQueryResult) GetFeature(feature any) (*FeatureResult, error)

GetFeature returns a wrapper for the raw, uncasted value of the specified feature. To get the value of a feature as its appropriate Go type, use the UnmarshalInto method.

func (*OnlineQueryResult) GetFeatureValue 

func (result *OnlineQueryResult) GetFeatureValue(feature any) (any, error)

GetFeatureValue returns the raw, uncasted value of the specified feature. To get the value of a feature as its appropriate Go type, use the UnmarshalInto method.

func (*OnlineQueryResult) UnmarshalInto 

func (result *OnlineQueryResult) UnmarshalInto(resultHolder any) (returnErr *ClientError)

UnmarshalInto unmarshals OnlineQueryResult.Data into the specified struct (passed by pointer). The input argument should be a pointer to the struct that represents the output namespace.

  1. UnmarshalInto populates fields corresponding to outputs specified in OnlineQueryParams, while leaving all other fields as nil. If the struct has fields that point to other structs (has-one relations), those nested structs will also be populated with their respective feature values.

  2. UnmarshalInto validates that all expected output features (as specified in OnlineQueryParams) are not nil pointers, and returns a ClientError otherwise.

  3. UnmarshalInto also returns a ClientError if its argument is not a pointer to a struct.

Implicit usage example (pass result struct into OnlineQuery): 

func printUserDetails(chalkClient chalk.Client) {
	user := User{}
	chalkClient.OnlineQuery(chalk.OnlineQueryParams{}.WithOutputs(
		 Features.User.Family.Size,
		 Features.User.SocureScore
	).WithInput(Features.User.Id, 1), &user)

	fmt.Println("User family size: ", *user.Family.Size)
	fmt.Println("User Socure score: ", *user.SocureScore)
}

Equivalent explicit usage example: 

func printUserDetails(chalkClient chalk.Client) {
	result, _ := chalkClient.OnlineQuery(chalk.OnlineQueryParams{}.WithOutputs(
		Features.User.Family.Size,
		Features.User.SocureScore
	).WithInput(Features.User.Id, 1), nil)

	user := User{}
	result.UnmarshalInto(&user)

	fmt.Println("User family size: ", *user.Family.Size)
	fmt.Println("User Socure score: ", *user.SocureScore)
}

type ParamType added in v0.3.2 

type ParamType string
const (
	ParamTypeUnknown    ParamType = "unknown param"
	ParamOutput         ParamType = "output"
	ParamInput          ParamType = "input"
	ParamStaleness      ParamType = "staleness"
	ParamRequiredOutput ParamType = "required output"
)

type QueryMeta 

type QueryMeta struct {
	// Execution duration in seconds
	ExecutionDurationS float64 `json:"execution_duration_s"`

	// The id of the deployment that served this query.
	DeploymentId string `json:"deployment_id"`

	// The id of the environment that served this query. Not intended to be human-readable,
	// but helpful for support.
	EnvironmentId string `json:"environment_id"`

	// The short name of the environment that served this query. For example: "dev" or "prod".
	EnvironmentName string `json:"environment_name"`

	// 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.
	QueryId string `json:"query_id"`

	// At the start of query execution, Chalk computes 'datetime.now()'. This value is used
	// to timestamp computed features.
	QueryTimestamp *time.Time `json:"query_timestamp"`

	// 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.
	QueryHash string `json:"query_hash"`
}

QueryMeta represents metadata about a Chalk query.

type QueryName added in v0.3.6 

type QueryName = string

type QueryStatus 

type QueryStatus int

QueryStatus represents the status of an offline query. 

const (
	// QueryStatusPendingSubmission to the database.
	QueryStatusPendingSubmission QueryStatus = 1

	// QueryStatusSubmitted to the database, but not yet running.
	QueryStatusSubmitted QueryStatus = 2

	// QueryStatusRunning in the database.
	QueryStatusRunning QueryStatus = 3

	// QueryStatusError with either submitting or running the job.
	QueryStatusError QueryStatus = 4

	// QueryStatusExpired indicates the job did not complete before an expiration
	// deadline, so there are no results.
	QueryStatusExpired QueryStatus = 5

	// QueryStatusCancelled indicates the job was manually cancelled before it
	// errored or finished successfully.
	QueryStatusCancelled QueryStatus = 6

	// QueryStatusSuccessful indicates the job successfully ran.
	QueryStatusSuccessful QueryStatus = 7
)

type ResolverException 

type ResolverException struct {
	// The name of the class of the exception.
	Kind string `json:"kind"`

	// The message taken from the exception.
	Message string `json:"message"`

	// The stacktrace produced by the code.
	Stacktrace string `json:"stacktrace"`
}

type ServerError 

type ServerError struct {
	// The type of the error.
	Code ErrorCode `json:"code"`

	// The category of the error, given in the type field for the error codes.
	// This will be one of "REQUEST", "NETWORK", and "FIELD".
	Category ErrorCodeCategory `json:"category"`

	// A readable description of the error message.
	Message string `json:"message"`

	// The exception that caused the failure, if applicable.
	Exception *ResolverException `json:"exception"`

	// The fully qualified name of the failing feature, e.g. `user.identity.has_voip_phone`
	Feature string `json:"12feature"`

	// The fully qualified name of the failing resolver, e.g. `my.project.get_fraud_score`.
	Resolver string `json:"resolver"`
}

ServerError is an error that occurred in Chalk's server, for example, when a resolver unexpectedly fails to run.

func (*ServerError) Error 

func (e *ServerError) Error() string

type StdOutLeveledLogger 

type StdOutLeveledLogger struct {
	// Level is the minimum logging level that will be emitted by this logger.
	//
	// For example, a Level set to LevelWarn will emit warnings and errors, but
	// not informational or debug messages.
	//
	// Always set this with a constant like LevelWarn because the individual
	// values are not guaranteed to be stable.
	Level Level
	// contains filtered or unexported fields
}

StdOutLeveledLogger is a leveled logger implementation.

It prints warnings and errors to `os.Stderr` and other messages to `os.Stdout`.

func (*StdOutLeveledLogger) Debugf 

func (l *StdOutLeveledLogger) Debugf(format string, v ...interface{})

Debugf logs a debug message using Printf conventions.

func (*StdOutLeveledLogger) Errorf 

func (l *StdOutLeveledLogger) Errorf(format string, v ...interface{})

Errorf logs a warning message using Printf conventions.

func (*StdOutLeveledLogger) Infof 

func (l *StdOutLeveledLogger) Infof(format string, v ...interface{})

Infof logs an informational message using Printf conventions.

func (*StdOutLeveledLogger) Warnf 

func (l *StdOutLeveledLogger) Warnf(format string, v ...interface{})

Warnf logs a warning message using Printf conventions.

type TriggerResolverRunParams 

type TriggerResolverRunParams struct {
	// ResolverFqn is the fully qualified name of the offline resolver to trigger.
	ResolverFqn string `json:"resolver_fqn"`

	// EnvironmentId is the environment under which you'd like to query your data.
	EnvironmentId string `json:"environment_id"`

	// PreviewDeploymentId, if specified, will be used by Chalk to route
	// your request to the relevant preview deployment.
	PreviewDeploymentId string `json:"preview_deployment_id"`
}

type TriggerResolverRunResult 

type TriggerResolverRunResult struct {
	// Id is the ID of the offline resolver run.
	Id string `json:"id"`

	// Status is the current status of the resolver run.
	Status string `json:"status"`
}

type TsFeatureValue 

type TsFeatureValue struct {
	// The value of the feature. In the context of offline query,
	// this is always a value of a primary feature.
	Value any

	// The observation time at which you would like the output
	// feature values to be queried. If nil, [OfflineQueryParams.DefaultTime]
	// will be used as the observation time. If [OfflineQueryParams.DefaultTime]
	// is also nil, the current time will be used as the observation time.
	ObservationTime *time.Time
}

TsFeatureValue is a struct that can be passed to OfflineQueryParams.WithInput to specify the value of a feature along with a timestamp. This timestamp indicates the observation time at which you would like the output feature values to be queried. For more information about observation time, see Temporal Consistency.

type UploadFeaturesParams added in v0.3.13 

type UploadFeaturesParams struct {
	// Inputs is a map of features to values. The features should
	// either be a string or codegen-ed Feature object. The values
	// should be a slice of the appropriate type. All slices should
	// be the same length as the number of entities you want to upload
	// features for.
	Inputs map[any]any

	// EnvironmentOverride is the environment to which you want to upload
	// features. If not specified, defaults to the environment specified
	// in the client configuration.
	EnvironmentOverride string

	// PreviewDeploymentId is the preview deployment to which you want to upload
	// features. If not specified, defaults to the main deployment.
	PreviewDeploymentId string
}

UploadFeaturesParams defines the parameters that help you execute an upload features request.

type UploadFeaturesResult added in v0.3.13 

type UploadFeaturesResult struct {
	OperationId string `json:"operation_id"`
}

UploadFeaturesResult holds the result of an upload features request.

Source Files

View all Source files

Directories

Path Synopsis
gen
chalk/arrow/v1
chalk/artifacts/v1
chalk/auth/v1
chalk/common/v1
chalk/engine/v1
chalk/engine/v1/enginev1connect
chalk/expression/v1
chalk/graph/v1
chalk/lsp/v1
chalk/pubsub/v1
chalk/server/v1
chalk/server/v1/serverv1connect
chalk/usage/v1
chalk/utils/v1
gen_bq_schema
auth
colls
tests/integration

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.