qri and dataset modules

In Qri’s starlark there are three “nonstandard” modules specific to qri. These modules are not considered part of the standard library project, and are defined in a different repository. They’re described here to keep documentation complete:

In addition, there are some special built-in functions.

qri module

access this method from the qri module, eg qri.list_datasets()

To load:

load("qri.star", "qri")

Function Definitions:

list_datasets

qri.list_datasets()

returns list of datasets references available on your qri node

load("qri.star", "qri")

def transform(ds,ctx):
  datasets = qri.list_datasets()
  #
  # prints a list of string dataset references
  print(datasets) 
  #
  # create a dataset that contains a list of your datasets:
  ds.set_body(datasets)

context object - ctx

you can access these methods from the context object. A context object gets passed into the transform and download functions, and by convention is named ctx

get_config

ctx.get_config(key)

returns the value of a config variable, declared in the dataset file:

# in the dataset.yaml file:
transform:
  scriptpath: transform.star
  config:
    key: value

Example usage:

def transform(ds, ctx):
  ds.set_body([ctx.get_config("key")])

get_secret

qri.get_secret(key)

returns the value of a secrets variable, declared in the dataset file:

# in the dataset.yaml file:
transform:
  scriptpath: transform.star
  secrets:
    key: value

dataset object - ds

you can access these methods from the dataset object. A dataset object gets passed into the transform function, and by convention is named ds

Function Definitions:

get_body

ds.get_body()

returns the body of the previous version of the dataset as a list or dictionary

set_body

ds.set_body(body, raw)

body should usually be a list or a dictionary. raw is a boolean value. If true, it expects body to be a string and will store the body as byte data. Returns None.

set_meta

ds.set_meta(field, value)

Sets a specific field of the meta to the value. field and value are both strings. Returns None.

def transform(ds,ctx):
  ds.set_meta("title", "Reference Transform")
  return ds

set_schema

ds.set_schema(value)

value is a dictionary written as a json schema. Returns None

def transform(ds,ctx):
  schema = {
    "type": "array",
    "items": {
      "type": "array",
      "items": [{
          "description": "type of animal",
          "title": "Animal",
          "type": "string"
        }, {
          "description": "number of legs this animal has",
          "title": "Number of Legs",
          "type": "integer"
        }
      ]
    }
  }
  structure = {
    "format": "json",
    "schema": schema
  }

  ds.set_structure(structure)
  ds.set_body([
    ["cat", 4],
    ["bird", 2],
    ["snake", 0]
  ])
  return ds

built-ins

Function Definitions:

load_dataset

load_dataset(ref)

Loads a dataset from your repo or the distributed web using a reference string. Returns it as a dataset object.

error

error("message")

Halts program execution with an error