Spectre Properties

For Spectre, properties refer to strings attached to various objects that Spectre works on.

TIP: Spectre properties are separate from User Properties defined for a server.

System properties vs custom properties

There are two kinds of Spectre properties: system properties and custom properties.

System properties are defined and used by Spectre. Some system properties can be set by users (for example, label and format), and some are set only by Spectre itself. Most system properties can be set using syntax like property=value, but some use the property tag. For instance, format and label are defined using the former method, and Description is defined using the latter:

  column "units_sold" type="integer" format="#,#" label="Units Sold" {
    property "Description" "How many units were sold"
  }

Custom properties are not used by Spectre but are available for users to add their own metadata to Spectre objects. These use the custom-property tag, for instance:

  column "units_sold" type="integer" {
    custom-property "My Prop" "A"
  }

Custom properties can be referenced in Spectre expressions using functions like column_custom_property(). In some cases, users can reach system properties using column_system_property().

Column properties

Column properties are attached to columns in a cBase. Here are some system properties available on columns:

"Definition" (property "Definition" "...", any string)
"Description" (property "Description" "...", any string)
"Duration" (duration=..., boolean)
"Format" (format="...", uses special format string syntax)
"Good Direction" (property "Good Direction" "...", should be "up" or "down", may support others later)
"Label" (label="...", any string)
"Natural Sort" (sort-natural=..., boolean)
"Reference" (property "Reference" "...", any string)
"Suggested Dimension" (suggested-dimension=..., boolean)
"Summary Type" (summary-type="...", a summary function name e.g. "average")
"TimeZone" (timezone="...", an ICU time zone name)

NOTE: See this list for all ICU time zone names: ICU Time Zones.

Column properties can be referenced with column_system_property() and column_custom_property().

Calc properties

Properties also exist on calcs in a cPlan. They are set in a similar way:

  calc "max_units" `max(value("Units"))` label="Max Units" {
    property "Description" "The biggest units number"
  }

Calc properties can also be copied from one calc to another. For example, here the format defined for units_sold is also applied to max_units:

  calc "units_sold" `sum(value("Units"))` format="#,#" 
  calc "max_units" `max(value("Units"))` {
    copy-properties-from "units_sold"
  }

All column properties are also calc properties. When a calc is automatically generated from a cBase column it inherits the properties from the column, so a column Units in a cBase automatically gets a calc Units in the cPlan with the same properties as the cBase column.

There is one system property for calcs which is not available on columns:

"Filter Expression" (filter=`...`, an expression)

Calc properties can be referenced with calc_custom_property() and calc_system_property().

Table properties

Properties also exist on cBases. They can be set in the build using the property and custom-property tags, but in some cases there are special tags to set them (for example, locale). Here are some system properties available on tables:

"Build Timestamp" (automatically set)
"Column Order" (property "Column Order" "preserve", this is the only option)
"Current Date" (property "Current Date" "...", must be a date with format "YYYY/MM/DD")
"Date Dimension" (property "Date Dimension" "...", must be the name of a column)
"Description" (property "Description" "...", any string)
"Extract Timestamp" (extract-time "...", can be "now", or a date/time with format "YYYY-MM-DD HH:MM:SS" or "YYYY-MM-DD")
"Locale" (locale "...", a locale string e.g. "en_US")

Table properties can be referenced with table_system_property() and table_custom_property().

NOTE: Starting with Spectre 7.1(19), properties can be set on all input types: cbase-input, dive-input, text-input, and tunnel-input.

cPlan properties

Spectre 7.1(19) adds properties to cPlans. They are set using the property and custom-property tags. Spectre cPlans can have the same properties as tables.

All table properties are also cPlan properties. When a cPlan has only a single cBase input, then it will inherit the table properties from that cBase. A cPlan with multiple inputs does not inherit any properties.

cPlan properties can be referenced with cplan_system_property() and cplan_custom_property().