chalk

package module
v0.19.2 Latest Latest
Warning

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

 Go to latest Published: Dec 19, 2024 License: Apache-2.0 Imports: 35 Imported by: 1

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",
})
gRPC Client

To use gRPC as the underlying protocol for communication with Chalk, set the UseGrpc field in ClientConfig to true.

client, err := chalk.NewClient(&chalk.ClientConfig{
    UseGrpc: true,
})

You can then make requests just like you would without UseGrpc specified.

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, "u273489057").
		WithInput(Features.User.Transactions, []Transaction{
            {Id: utils.ToPtr("sd8f76"), Amount: utils.ToPtr(13.23)},
            {Id: utils.ToPtr("jk546d"), SeriesId: utils.ToPtr(48.95)},
        }).
        WithOutputs(Features.User.Id, Features.User.LastName),
    &user,
)
Named Queries

If your deployment contains named queries, you can specify a query name instead of outputs when making a query.

user := User{}
_, err = client.OnlineQuery(
    chalk.OnlineQueryParams{}.
        WithInput(Features.User.Id, "u273489057").
        WithQueryName("user_underwriting_features"),
    &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"},
        },
    },
)
Update Aggregates

Note: This method is available only when using the gRPC client. See gRPC Client for more information.

You can easily update your windowed aggregation feature values with UpdateAggregates. For example, with this feature definition:

@features
class User:
    id: str
    txns: "DataFrame[Transaction]"
    txn_amount_total: Windowed[int] = windowed(
        "30d",
        "90d",
        materialization={
            "bucket_duration": "1d",
        },
        expression=_.txns[_.amount].sum(),
    )

@features
class Transaction:
    id: Primary[str]
    amount: float
    user_id: str

Then to update the txn_amount_total feature, you would upload features corresponding to that aggregation:

res, err := client.UpdateAggregates(
    chalk.UpdateAggregatesParams{
        Inputs: map[any]any{
            "transaction.id": []string{"txn-1", "txn-2"},
            "transaction.user_id": []string{"user-1", "user-2"},
            "transaction.amount": []float64{100.0, 200.0},
            "transaction.__chalk_observed_at__": []time.Time{time.Now(), time.Now()},
        },
    },
)

Note that if you have an explicit FeatureTime feature specified, you could provide that in place of the __chalk_observed_at__ column.

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 ConvertTableToRows added in v0.16.21 

func ConvertTableToRows(table arrow.Table) ([]map[string]any, error)

func DesuffixFqn 

func DesuffixFqn(fqn string) string

func InitFeatures 

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

func SnakeCase added in v0.8.2 

func SnakeCase(s string) string

func UnmarshalOnlineQueryBulkResponse added in v0.16.14 

func UnmarshalOnlineQueryBulkResponse(response *commonv1.OnlineQueryBulkResponse, resultHolders any) error

func UnmarshalOnlineQueryResponse added in v0.16.14 

func UnmarshalOnlineQueryResponse(response *commonv1.OnlineQueryResponse, resultHolder any) 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 ChunkResult added in v0.18.27 

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

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)

	// UpdateAggregates synchronously persists feature values that back windowed aggregations,
	// while updating the corresponding aggregate values themselves.
	// The `Inputs` parameter should be a map of features to values. The features should either
	// be a string or codegen-ed Feature object, and the values a slice of the appropriate type.
	// All slices should be the same length.
	//
	// The update is successful if the response contains no errors.
	//
	// Example:
	//
	// 		res, err := client.UpdateAggregates(
	// 			UpdateAggregatesParams{
	// 				Inputs: map[any]any{
	// 					Features.Txns.Id: []string{5555-5555", "4444-4444"},
	// 				    "txns.merchant_id": []string{"amezon", "pacman studios"},
	//					"txns.amount": []float64{126.58, 100.03},
	// 				},
	// 			}
	// 		)
	//      if err != nil {
	//          return err.Error()
	//      }
	//
	// [chalk codegen]: https://docs.chalk.ai/cli#codegen
	UpdateAggregates(args UpdateAggregatesParams) (UpdateAggregatesResult, 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)

	// GetToken retrieves a token that can be used to authenticate requests to the Chalk API
	// along with other using the client's credentials.
	GetToken() (*TokenResult, error)

	GetAggregates(ctx context.Context, features []string) (*aggregatev1.GetAggregatesResponse, error)

	PlanAggregateBackfill(
		ctx context.Context,
		req *aggregatev1.PlanAggregateBackfillRequest,
	) (*aggregatev1.PlanAggregateBackfillResponse, 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(configs ...*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

	// Chalk can route queries to specific deployments using deployment
	// tags.
	DeploymentTag string

	// Chalk routes performance sensitive requests like online query
	// directly to the query server that runs the engine. Populate
	// this field if you would like to route these requests to a
	// different query server than the one automatically resolved
	// by Chalk.
	QueryServer 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

	// UseGrpc, if set to true, will create a gRPC client instead of a REST client.
	UseGrpc bool
}

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, fqnToValue map[Fqn]any, expectedOutputs []string) (returnErr *ClientError)

UnmarshalInto unmarshals a map with keys being FQNs and values being the value for a singular feature (rather than a list of values for multiple pkeys) into a struct whose fields correspond to the FQNs. An illustration: 

type FinancialMetric struct {
	Id *string
	BusinessId *string
	MetricDate *time.Time
}

func main() {
	fqnToValue := map[Fqn]any{
		"FinancialMetric.Id": "id1",
		"FinancialMetric.BusinessId": "business_id1",
		"FinancialMetric.MetricDate": time.Now(),
	}
	fm := FinancialMetric{}
	if err := UnmarshalInto(&fm, fqnToValue, nil); err != (*ClientError)(nil) {
		fmt.Println(err)
	} else {
		fmt.Println(fm)
	}
}

func UnmarshalTableInto added in v0.7.0 

func UnmarshalTableInto(table arrow.Table, resultHolders any) *ClientError

UnmarshalTableInto unmarshals the given Arrow table into the given result holders. The result holders should be a pointer to a slice of structs.

Usage: 

func printNumRelatives(chalkClient chalk.Client) {
	result, _ := chalkClient.OnlineQueryBulk(chalk.OnlineQueryParams{}.WithOutputs(
		Features.User.Relatives,
	).WithInput(Features.User.Id, []int{1, 2}), nil)

	relatives := make([]Relative, 0)
	result.UnmarshalInto(&relatives)

	feature, _ := chalk.UnwrapFeature(Features.User.Relatives)
	fmt.Println("Number of relatives for all users: ", len(result.GroupsTable[feature.Fqn]))

}

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 FeatureEncodingOptions added in v0.17.0 

type FeatureEncodingOptions struct {
	// If true, Chalk will return structs as objects
	// instead of arrays in the response.
	EncodeStructsAsObjects bool `json:"encode_structs_as_objects"`
}

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.
	// <<< NOTE >>> This value is nullable, and if it is null, it will be set
	// to the zero value of `time.Time`.
	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 GRPCClient added in v0.16.14 

type GRPCClient interface {
	OnlineQuery(ctx context.Context, params OnlineQueryParamsComplete) (*commonv1.OnlineQueryResponse, error)

	OnlineQueryBulk(ctx context.Context, params OnlineQueryParamsComplete) (*commonv1.OnlineQueryBulkResponse, error)

	UpdateAggregates(ctx context.Context, params UpdateAggregatesParams) (*commonv1.UploadFeaturesBulkResponse, error)

	GetAggregates(ctx context.Context, features []string) (*aggregatev1.GetAggregatesResponse, error)

	PlanAggregateBackfill(
		ctx context.Context,
		req *aggregatev1.PlanAggregateBackfillRequest,
	) (*aggregatev1.PlanAggregateBackfillResponse, error)

	// GetToken retrieves a token that can be used to authenticate requests to the Chalk API
	// along with other using the client's credentials.
	GetToken() (*TokenResult, error)
}

GRPCClient is the gRPC-native interface for interacting with Chalk. Our existing Client interface also works with gRPC, but this interface is more idiomatic for talking to our gRPC endpoints.

func NewGRPCClient added in v0.16.14 

func NewGRPCClient(configs ...*GRPCClientConfig) (GRPCClient, error)

NewGRPCClient creates a GRPCClient with authentication settings configured. These settings can be overriden by passing in a ClientConfig object. Otherwise, for each configuration variable, NewGRPCClient uses its corresponding environment variable if it exists. The environment variables that NewGRPCClient 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, NewGRPCClient 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, err := chalk.NewGRPCClient(&chalk.ClientConfig{
	        ClientId:      "id-89140a6614886982a6782106759e30",
	        ClientSecret:  "sec-b1ba98e658d7ada4ff4c7464fb0fcee65fe2cbd86b3dd34141e16f6314267b7b",
	        ApiServer:     "https://api.chalk.ai",
	        EnvironmentId: "qa",
	        Branch:        "jorges-december",
})

type GRPCClientConfig added in v0.16.14 

type GRPCClientConfig 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

	// Chalk routes performance sensitive requests like online query
	// directly to the query server that runs the engine. Populate
	// this field if you would like to route these requests to a
	// different query server than the one automatically resolved
	// by Chalk.
	QueryServer 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 instantiating a
	// Connect gRPC-compatible client.
	//
	// If left unset, it'll be set to a default HTTP client for the package.
	HTTPClient HTTPClient

	// Chalk can route queries to specific deployments using deployment
	// tags.
	DeploymentTag 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

	// The tags used to scope the resolvers.
	Tags []string
	// 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) WithInputs added in v0.17.1 

func (p OfflineQueryParams) WithInputs(inputs map[any][]any) offlineQueryParamsWithInputs

WithInputs returns a copy of Offline Query parameters with the specified inputs added. For use via method chaining. See OfflineQueryParamsComplete for usage examples. The value of the inputs map 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()

func (*OnlineQueryBulkResult) UnmarshalInto added in v0.7.0 

func (r *OnlineQueryBulkResult) UnmarshalInto(resultHolders any) *ClientError

UnmarshalInto unmarshals Arrow tables in OnlineQueryBulkResult into the specified slice of structs (passed by pointer). The input argument should be a pointer to the empty slice of structs 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 also returns a ClientError if its argument is not a pointer to a list of structs.

  3. UnmarshalInto does not currently handle unmarshalling: a. has-many features In the meantime, you can manually unmarshal a has-many feature across all root structs by using the UnmarshalTableInto function.

Usage example: 

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

	var users []User
	result.UnmarshalInto(&users)

	fmt.Println("User 1 family size: ", *user[0].Family.Size)
	fmt.Println("User 2 Socure score: ", *user[1].SocureScore)
}

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

	// The version of the query you're making, for example, "v1".
	QueryNameVersion 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

	// RequiredResolverTags are all the [tags] that must be present on a resolver for
	// it to be considered eligible to execute.
	// [tags]: https://docs.chalk.ai/docs/resolver-tags
	RequiredResolverTags []string

	// Now is the time value that will be passed into [Now] dependent resolvers.
	// [Now]: https://docs.chalk.ai/docs/time#now-explicitly-time-dependent-resolvers
	Now []time.Time

	// StorePlanStages triggers storing the output of each of the query plan stages in
	// S3/GCS. This will dramatically impact the performance of the query, so it should
	// only be used for debugging. These files will be visible in the web dashboard's
	// query detail view, and can be downloaded in full by clicking on a plan node in
	// the query plan visualizer.
	StorePlanStages bool

	// Explain will log the query execution plan. Requests using `explain=True` will be
	// slower than requests using `explain=False`. If `true`, `IncludeMeta` will be set
	// to `true` as well.
	Explain bool

	// EncodingOptions is used to specify how features should be encoded in the response.
	EncodingOptions *FeatureEncodingOptions
	// 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

WithBranchId returns a copy of Online Query parameters with the branch id added. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

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) WithInputs added in v0.17.1 

func (p OnlineQueryParams) WithInputs(inputs map[any]any) onlineQueryParamsWithInputs

WithInputs 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) WithQueryName added in v0.14.0 

func (p OnlineQueryParams) WithQueryName(name string) onlineQueryParamsWithOutputs

WithQueryName returns a copy of Online Query parameters with the specified query name set. For use via method chaining. See OnlineQueryParamsComplete for usage examples.

func (OnlineQueryParams) WithQueryNameVersion added in v0.14.0 

func (p OnlineQueryParams) WithQueryNameVersion(version string) OnlineQueryParams

WithQueryNameVersion returns a copy of Online Query parameters with the query name version 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.

func (OnlineQueryParams) WithTags added in v0.17.4 

func (p OnlineQueryParams) WithTags(feature ...string) OnlineQueryParams

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

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(options ...*SerializationOptions) ([]byte, error)

func (OnlineQueryParamsComplete) WithBranchId added in v0.4.7 

func (p OnlineQueryParamsComplete) WithBranchId(branchId string) OnlineQueryParamsComplete

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

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) WithInputs added in v0.17.1 

func (p OnlineQueryParamsComplete) WithInputs(inputs map[any]any) OnlineQueryParamsComplete

WithInputs returns a copy of Online Query parameters with the specified inputs 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) WithQueryName added in v0.14.0 

func (p OnlineQueryParamsComplete) WithQueryName(queryName string) OnlineQueryParamsComplete

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

func (OnlineQueryParamsComplete) WithQueryNameVersion added in v0.14.0 

func (p OnlineQueryParamsComplete) WithQueryNameVersion(queryNameVersion string) OnlineQueryParamsComplete

WithQueryNameVersion returns a copy of Online Query parameters with the specified input 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.

func (OnlineQueryParamsComplete) WithTags added in v0.17.4 

func (p OnlineQueryParamsComplete) WithTags(tags ...string) OnlineQueryParamsComplete

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

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 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 SerializationOptions added in v0.5.1 

type SerializationOptions struct {
	ClientConfigBranchId string
}

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 TokenResult added in v0.13.9 

type TokenResult struct {
	// The access token that can be used to authenticate requests to the Chalk API.
	AccessToken string `json:"access_token"`

	// The primary environment that the token is scoped to.
	PrimaryEnvironment string `json:"primary_environment"`

	// The time at which the token expires.
	ValidUntil time.Time `json:"valid_until"`

	// The GRPC endpoint for the engine.
	Engines map[string]string `json:"engines"`
}

TokenResult holds the result of a GetToken request.

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 UpdateAggregatesParams added in v0.14.0 

type UpdateAggregatesParams 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

	Context context.Context
}

UpdateAggregatesParams lets you specify parameters for updating aggregated values of your windowed aggregation features.

type UpdateAggregatesResult added in v0.14.0 

type UpdateAggregatesResult struct {
	TraceId string `json:"trace_id"`
}

UpdateAggregatesResult holds the result of an upload aggregates request.

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/aggregate/v1
chalk/aggregate/v1/aggregatev1connect
chalk/arrow/v1
chalk/artifacts/v1
chalk/auth/v1
chalk/chart/v1
chalk/common/v1
chalk/engine/v1
chalk/engine/v1/enginev1connect
chalk/engine/v2
chalk/engine/v2/enginev2connect
chalk/expression/v1
chalk/graph/v1
chalk/graph/v2
chalk/kubernetes/v1
chalk/lsp/v1
chalk/manager/v1
chalk/manager/v1/managerv1connect
chalk/metrics/v4
chalk/pubsub/v1
chalk/server/v1
chalk/server/v1/serverv1connect
chalk/usage/v1
chalk/utils/v1
gen_bq_schema
grpc/health/v1
grpc/health/v1/healthv1connect
auth
colls
ptr
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.