Parameter types

Times Square notebooks use parameters to pass inputs into the notebook. Different types of parameters are supported, and these types inform the interface for users to enter values and the validation that’s performed on those values. You define parameters in a notebook’s sidecar YAML-formatted metadata file and their values are assigned in the notebook’s parameters cell, which is always the first code cell in the notebook. This page lists the different types of parameters that are supported.

Strings

A string is the most basic parameter type that supports any kind of text. There isn’t any validation performed on the string.

Notebook YAML sidecar
parameters:
  message:
    type: string
    description: A message to display.
    default: "Hello world"
Notebook parameters cell
message = "Hello world"

Dates

Dates (without times) are a format of the basic string type. Users enter dates in the format YYYY-MM-DD (ISO 8601) and your notebook receives the date as a datetime.date object.

Notebook YAML sidecar
parameters:
  start_date:
    type: string
    format: date
    description: An ISO8601 date
    default: "2024-01-01"
Notebook parameters cell
import datetime

start_date = datetime.date.fromisoformat("2024-01-01")

Note how Times Square automatically imports the datetime module for you in the parameters cell to parse the date into a datetime.date object. Replicate this pattern in the default parameters cell of your notebook.

Date and time

Dates and times are another format of the basic string type that specify a precise moment in time. Date and time parameters are entered in the format YYYY-MM-DDTHH:MM:SS+HH:MM (ISO 8601) and your notebook receives the date as a datetime.datetime object. Note that a time zone is required. Besides specifying a time zone offset, you can also use the Z suffix to indicate UTC.

Notebook YAML sidecar
parameters:
  start_time:
    type: string
    format: date-time
    description: An ISO8601 date and time
    default: "2024-01-01T12:00:00Z"
Notebook parameters cell
import datetime

start_time = datetime.datetime.fromisoformat("2024-01-01T12:00:00Z")

Note how Times Square automatically imports the datetime module for you in the parameters cell to parse the date into a datetime.date object. Replicate this pattern in the default parameters cell of your notebook.

Integers

For decimal numbers, use the integer type. In your code, these values are Python int objects.

Notebook YAML sidecar
parameters:
  number:
    type: integer
    description: An integer
    default: 42
Notebook parameters cell
number = 42

Validation constraints

The integer type supports validation constraints. You can specify minimum values and maximum values (both or either):

Notebook YAML sidecar
parameters:
  number:
    type: integer
    description: An integer
    default: 42
    minimum: 0
    maximum: 100

Floating point numbers

For floating point numbers, use the number type. In your code, these values are Python float objects.

Notebook YAML sidecar
parameters:
  number:
    type: number
    description: A number
    default: 27.5
Notebook parameters cell
number = 27.5

Validation constraints

Like the integer type, the number type supports validation constraints. You can specify minimum values and maximum values (both or either):

Notebook YAML sidecar
parameters:
  number:
    type: number
    description: A number
    default: 27.5
    minimum: 0
    maximum: 100

Booleans

Boolean (true/false) values are supported with the boolean type. The string representation is based on JSON’s true and false values. To convert the string into a Python boolean, you can compare the string: In your code, these values are Python bool (True / False) objects.

Notebook YAML sidecar
parameters:
  switch_param:
    type: boolean
    description: A boolean
    default: true
Notebook parameters cell
switch_param = True