Skip to main content

@rtorcato/cf-common

Interfaces​

DatasetSchema​

Defined in: index.ts:10

Column names for one dataset, in slot order: blobs[0] is written to blob1, doubles[0] to double1, and index (if set) to index1.

Properties​

blobs?​

readonly optional blobs?: readonly string[]

Defined in: index.ts:11

doubles?​

readonly optional doubles?: readonly string[]

Defined in: index.ts:12

index?​

readonly optional index?: string

Defined in: index.ts:13


Dataset​

Defined in: index.ts:26

A dataset with named columns.

Type Parameters​

S​

S extends DatasetSchema

Properties​

columns​

readonly columns: Readonly<Record<Names<S["blobs"]> | Names<S["doubles"]>, string>> & (S["index"] extends string ? { readonly [K in string]: "index1" } : unknown)

Defined in: index.ts:30

Each column name mapped to its SQL API column (blob1, double1, index1), for building queries.

Methods​

write()​

write(fields): void

Defined in: index.ts:28

Write one data point. Throws ANALYTICS_WRITE_FAILED.

Parameters​
fields​

DataPointFields<S>

Returns​

void

Type Aliases​

BlobValue​

BlobValue = string | ArrayBuffer | null

Defined in: index.ts:4

A blob value: a string, raw bytes, or null for an empty slot.


DataPointFields​

DataPointFields<S> = { [K in Names<S["blobs"]>]?: BlobValue } & { [K in Names<S["doubles"]>]: number } & (S["index"] extends string ? { [K in S["index"]]: string } : unknown)

Defined in: index.ts:19

One data point by column name. Blobs are optional (null when missing); doubles and the index are required.

Type Parameters​

S​

S extends DatasetSchema

Functions​

writeDataPoint()​

writeDataPoint(dataset, point): void

Defined in: index.ts:46

Write one data point to an Analytics Engine dataset. The binding is fire-and-forget, so this returns nothing and never waits on the network.

Limits: 20 blobs, 20 doubles, one index of at most 96 bytes, 16 KB of blobs per point. If the binding throws (a point it rejects), the error becomes a non-exposed 500 with code ANALYTICS_WRITE_FAILED and the original as cause.

Example​

const events = getBinding<AnalyticsEngineDataset>(env, 'EVENTS')
writeDataPoint(events, { blobs: [path, country], doubles: [ms], indexes: [customerId] })

Parameters​

dataset​

AnalyticsEngineDataset

point​

AnalyticsEngineDataPoint

Returns​

void


createDataset()​

createDataset<S>(dataset, schema): Dataset<S>

Defined in: index.ts:74

Name a dataset's columns once, then write by name instead of by position. Declare the schema as const (or inline) so the column names are literal types. Changing the order of an existing schema moves data between columns, so only append.

Example​

const requests = createDataset(getBinding<AnalyticsEngineDataset>(env, 'REQUESTS'), {
blobs: ['path', 'country'],
doubles: ['latencyMs', 'status'],
index: 'customerId',
})
requests.write({ path: '/api', country: 'CA', latencyMs: 12, status: 200, customerId: 'c_1' })
requests.columns.latencyMs // 'double1'

Type Parameters​

S​

S extends DatasetSchema

Parameters​

dataset​

AnalyticsEngineDataset

schema​

S

Returns​

Dataset<S>