The Declare statement is used to create field and group definitions, where you can define relations between fields or functions. A set of field definitions can be used to automatically generate derived fields, which can be used as dimensions. For example, you can create a calendar definition, and use that to generate related dimensions, such as year, month, week and day, from a date field.
You can use Declare to either set up a new field definition, or to create a field definition based on an already existing definition.
Setting up a new field definition
Syntax:
definition_name:
Declare [Field[s]] Definition [Tagged tag_list ]
[Parameters parameter_list ]
Fields field_list
Arguments:
| Argument | Description |
|---|---|
| definition_name |
Name of the field definition, ended with a colon. Example: Calendar: |
| tag_list |
A comma separated list of tags to apply to fields derived from the field definition. Optional. Example: '$date' See: Field tags |
| parameter_list |
A comma separated list of parameters. A parameter is defined in the form name=value and is assigned a start value, which can be overridden when a field definition is re-used. Optional. Example: first_month_of_year = 1 |
| field_list |
A comma separated list of fields to generate when the field definition is used. A field is defined in the form <expression> As field_name tagged tag. Use $1 to reference the data field from which the derived fields should be generated. Example: Year($1) As Year tagged '$year' |
Example:
In this example we create a calendar definition that can be used to generate date related fields, such as year and month, that can be used in dimensions.
To try out the calendar we need some source data with date fields.
Now we can define a calendar that creates fields for year, month, week, weekday and day number.
The calendar is now defined, and you can apply it to the date fields that have been loaded, in this case OrderDate and ShippingDate, using a Derive clause.
When you have reloaded the data script, you can find the generated fields, for example OrderDate.Calendar.Weekday under Date & time fields in the Fields asset panel. They are also available in the expression editor and when you create dimensions, and can be used as any other field in visualizations.
Re-using an existing field definition
Syntax:
<definition name>:
Declare [Field][s] Definition
Using <existing_definition>
[With <parameter_assignment> ]
Arguments:
| Argument | Description |
|---|---|
| definition_name |
Name of the field definition, ended with a colon. Example: MyCalendar: |
| existing_definition |
The field definition to re-use when creating the new field definition. The new field definition will function the same way as the definition it is based on, with the exception if you use parameter_assignment to change a value used in the field expressions. Example: Using Calendar |
| parameter_assignment |
A comma separated list of parameter assignments. A parameter assignment is defined in the form name=value and overrides the parameter value that is set in the base field definition. Optional. Example: first_month_of_year = 4 |
Example:
In this example we re-use the calendar definition that was created in the previous example. In this case we want to use a fiscal year that starts in April. This is achieved by assigning the value 4 to the first_month_of_year parameter, which will affect the DayNumberOfYear field that is defined.
The example assumes that you use the sample data and field definition from the previous example.
When you have reloaded the data script, the generated fields are available in the sheet editor, with names OrderDate.MyCalendar.* and ShippingDate.MyCalendar.*.
Learn more
Did this page help you?
If you find any issues with this page or its content – a typo, a missing step, or a technical error – let us know how we can improve!