Navigation :

vector

vector, keyword

The vector keyword declares a user-defined vector function when it appears after def.

‘def vector name«tables»(args) with’, vector function definition

A vector function binds table parameters between << and >>. Inside the function body, expect table declares the tables and dimensions required by the function.

Unlike pure and process functions, a vector function body may use table-prefixed vectors and may aggregate from one declared table into another.

The returned values must be vectors defined on the declared tables. A vector function may return a single vector or a tuple of vectors.

When returning a tuple, all returned vectors must belong to the same table. When a vector function is called with scalar values only, it can also return a scalar value.

Examples

def vector daysAfterFirstSale<<Products, Sales>>(
  Sales.Date : date) with
  expect table Products[sku]
  expect table Sales expect [sku]
  Products.FirstSale = first(Sales.Date) sort Sales.Date
  Sales.Age = Sales.Date - Products.FirstSale
  return Sales.Age

table Products[sku] = with
  [| as sku, as Label |]
  [| "shirt", "Shirt" |]
  [| "hat", "Hat" |]

table Sales = with
  [| as ProductSku, as Date, as Qty |]
  [| "shirt", date(2024, 1, 3), 2 |]
  [| "shirt", date(2024, 1, 8), 1 |]
  [| "hat", date(2024, 1, 5), 3 |]

keep where Sales.sku = Sales.ProductSku

Sales.DaysAfterFirst = daysAfterFirstSale<<Products, Sales>>(Sales.Date)

show table "Sales lines" with
  Sales.ProductSku
  Sales.Date
  Sales.Qty
  Sales.DaysAfterFirst

Scalar-only calls can use the vector-function pipeline and define local tables:

def vector innerSum(n : number) with
  table Inner = extend.range(n)
  return sum(Inner.N) when (Inner.N mod 2 == 0)

result = innerSum(6)

Table parameters can expose their primary dimension inside the vector function:

def vector shippedBefore<<Items, Orders>>(Orders.Qty : number) with
  expect table Items[id]
  expect table Orders expect [id]
  Items.Total = sum(Orders.Qty)
  return Items.Total

Exporting a vector function

Vector functions can be exported from modules with export def vector. An importing script can call them through the module alias or import their name through a with block.

For example, the following module sums sales quantities per product:

// Module "/sample/sales-metrics"
export def vector totalQty<<Products, Sales>>(Sales.Qty : number) with
  expect table Products[sku]
  expect table Sales expect [sku]
  Products.Total = sum(Sales.Qty)
  return Products.Total

The importing script supplies its own tables and quantity vector:

import "/sample/sales-metrics" as Metrics

table Products[sku] = with
  [| as sku |]
  [| "shirt" |]
  [| "hat" |]

table Sales = with
  [| as Product, as Qty |]
  [| "shirt", 2 |]
  [| "shirt", 3 |]
  [| "hat", 4 |]

keep where Sales.sku = Sales.Product
Products.Total = Metrics.totalQty<<Products, Sales>>(Sales.Qty)

show table "Totals" a1d3 with
  sku
  Products.Total

The table shows a total of 5 for “shirt” and 4 for “hat”.

Remarks