Variable transformations（变量转换(Variable transformations)）

Variable transformations allow builders in Workshop to apply common operations to variables, as well as chain operations together by referencing previous operations.

Transformation types

General operations

• String concatenation: Returns a string concatenation of given static text and/or variable values. If an array variable is inputted, the operation will concatenate and cast elements within the array into string. Builders may optionally specify a separate input to be added between elements.
• If/else statement: Runs a conditional statement to return a predefined output value or variable.
• Cast operation: Cast variables between different primitives. The following type castings are supported:
• String → Numeric: Pass in a string type containing only numeric characters to cast to a numeric type.
• String → Date: Pass in a string type containing a validly formatted date value and select the corresponding date format used in the Parser field. For example, if passing in a string variable with the value 06/26/24, select M/dd/yyyy as the corresponding parser format to cast to a date type.
• String → Timestamp: Pass in a string type containing a validly formatted timestamp value and select the corresponding timestamp format used in the Parser field. The timezone used when casting the outputted timestamp value may be defined either using the user’s local timezone, set statically via options in a dropdown, or set dynamically using a string reference or variable. For example, if passing in a string variable with value 2024 06 26 12:50 AM, select yyyy M dd hh:mm aa as the corresponding parser format to cast to a timestamp type.
• String → GeoPoint: Pass in a string type formatted as a [latitude], [longitude] pair to cast to a geopoint type. For example: 40.782142,-73.96596.
• String → GeoShape: Pass in a string type formatted in JSON with a shape type and an array of coordinates to cast to a geoshape type. For example: {"type":"Polygon","coordinates":[[[-73.9580917968885,40.80044406792189],[-73.98186087075722,40.76811683550534],[-73.97304465743831,40.76434392565562],[-73.94930767833077,40.79687062648023],[-73.9580917968885,40.80044406792189]]]}.
• Timestamp → Date: Pass in a timestamp type to cast to a date type. The timezone used when casting the outputted date value may be defined either using the user’s local timezone, set statically via options in a dropdown, or set dynamically using a string reference or variable. The inputted timestamp will be converted to a date using the absolute timestamp at the specified timezone.
• Date → Timestamp: Pass in a date type to cast to a timestamp type. The timezone used when casting the outputted date value may be defined either using the user’s local timezone, set statically via options in a dropdown, or set dynamically using a string reference or variable. The inputted date will be converted to a timestamp representing start of day at the specified timezone.
• Any -> String: Casting of any primitive type to a string may be done using the String concatenation operation.

Object set transforms

• Is empty: Runs a boolean check for the absence of objects in a given object set.
• Is not empty: Runs a boolean check for the presence of objects in a given object set.
• Object property: Returns a property value given a single object and specified property of that object type.
• Object set aggregation: Runs an aggregation over a specified property of a given object set. Supported aggregations include min, max, sum, average, and cardinality.
• Object RID: Returns the object RID for a given object.

Math operations

• Add: Returns the sum of given numeric values or variables.
• Subtract: Returns the difference between given numeric values or variables.
• Multiply: Returns the product of given numeric values or variables.
• Divide: Returns the quotient of given numeric values or variables.
• Absolute: Returns the absolute value of a given numeric value or variable.
• Negate: Returns the negated value of a given numeric value or variable.
• Round Up (Ceil): Returns the rounded up value to a specified precision of a given numeric value or variable.
• Round Down (Floor): Returns the rounded down value to a specified precision of a given numeric value or variable.
• Round Nearest: Returns the rounded value to a specified precision of a given numeric value or variable.
• Max: Returns the maximum value from a collection of numeric, date, or timestamp values or variables.
• Min: Returns the minimum value from a collection of numeric, date, or timestamp values or variables.

Date/time math

• Relative date: Returns a calculated date given a numeric value or variable, specifying the number of days, weeks, months or years to add or subtract, and a date value or variable.
• Relative time: Returns a calculated time given a numeric value, specifying the number of seconds, minutes, hours, days, weeks, months or years to add or subtract, and a time value or variable.
• Between dates: Returns the numeric difference between two given date values or variables. The returned difference can be calculated in days, weeks, months, or years.
• Between times: Returns the numeric difference between two given time values or variables. The returned difference can be calculated in seconds, minutes, hours, days, weeks, months, or years.
• Current date: Returns the current date.

Date comparisons

• Is on or after: Runs a boolean check on if the first given date value or variable is on or after the second given date value or variable.
• Is after: Runs a boolean check on if the first given date value or variable is after the second given date value or variable.
• Is on or before: Runs a boolean check on if the first given date value or variable is on or before the second given date value or variable.
• Is before: Runs a boolean check on if the first given date value or variable is before the second given date value or variable.
• Is equal: Runs a boolean check comparing two given date values or variables for equality.

Time comparisons

• Is on or after: Runs a boolean check on if the first given time value or variable is on or after the second given time value or variable.
• Is after: Runs a boolean check on if the first given time value or variable is after the second given time value or variable.
• Is on or before: Runs a boolean check on if the first given time value or variable is on or before the second given time value or variable.
• Is before: Runs a boolean check on if the first given time value or variable is before the second given time value or variable.
• Is equal: Runs a boolean check comparing two given time values or variables for equality.

Numeric comparisons

• Equal to: Runs a boolean check comparing given numeric values or variables for equality.
• Not equal to: Runs a boolean check comparing given numeric values or variables for non-equality.
• Less than: Runs a boolean check on if the first given numeric value or variable is less than the second given numeric value(s) or variable(s).
• Less than or equal to: Runs a boolean check on if the first given numeric value or variable is less than or equal to the second given numeric value(s) or variable(s).
• Greater than: Runs a boolean check on if the first given numeric value or variable is greater than the second given numeric value(s) or variable(s).
• Greater than or equal to: Runs a boolean check on if the first given numeric value or variable is greater than or equal to the second given numeric value(s) or variable(s).

String comparison

• Is: Runs a boolean check comparing given string values or variables for equality.
• Is not: Runs a boolean check comparing given string values or variables for non-equality.
• Contains: Runs a boolean check on if the second given string value(s) or variable(s) is a substring of the first given string value or variable.
• Does not contain: Runs a boolean check on if the second given string value(s) or variable(s) is a substring of the first given string value or variable.
• Starts with: Runs a boolean check on if the second given string value(s) or variable(s) is a prefix of the first given string value or variable.
• Ends with: Runs a boolean check on if the second given string value(s) or variable(s) is a suffix of the first given string value or variable.

Boolean comparisons

• Is true: Runs a boolean check on if a given boolean variable is true.
• Is false (NOT): Runs a boolean check on if a given boolean variable is false.
• Is null: Runs a boolean check on if a given variable is null.
• Is not null: Runs a boolean check on if a given variable is not null.

Geospatial

• Geohash from geopoint: Converts a given geopoint into a geohash value as a string.
• Latitude from geopoint: Returns the numeric latitude value from a given geopoint.
• Longitude from geopoint: Returns the numeric longitude value from a given geopoint.
• MGRS from geopoint: Converts a given geopoint into an MGRS value as a string.

Array operations

• Compose: Returns an array containing all values of the given arrays.
• Intersection: Returns an array containing only common values between the given arrays.
• Update element at: Returns an array with a specific element in the given array updated. A builder may specify the element to be updated by specifying the index representing the element's position within the array.
• Get element at: Returns a value corresponding to the element at a specified index within the given array and matching the array's type.
• Length: Returns a numeric value representing the number of elements within the given array.

Array checks

• Contains: Runs a boolean check for the presence of given values within a given array.
• Does not contain: Runs a boolean check for the absence of given values within a given array.
• Is subset of: Runs a boolean check on if a given array is a subset of another given array.
• Is null: Runs a boolean check on if a given array is null.
• Note: This transform will evaluate and display as "is empty" if an array variable reference is selected for the value.
• Is not null: Runs a boolean check on if a given array is not null.
• Note: This transform will evaluate and display as "is not empty" if an array variable reference is selected for the value.

Struct transforms

• Extract struct field: Returns a struct field value given a struct and field ID. See Extract a field from a struct for more details.

---

中文翻译

---

变量转换(Variable transformations)

变量转换允许 Workshop 中的构建者对变量执行常见操作，并通过引用先前操作来串联多个操作。

转换类型(Transformation types)

常规操作(General operations)

• 字符串拼接(String concatenation)： 返回给定静态文本和/或变量值的字符串拼接结果。如果输入数组变量，该操作将拼接数组中的元素并将其转换为字符串。构建者可选择指定一个单独输入，添加到各元素之间。
• If/else 语句(If/else statement)： 执行条件语句，返回预定义的输出值或变量。
• 类型转换(Cast operation)： 在不同原始类型之间转换变量。支持以下类型转换：
• 字符串 → 数值：传入仅包含数字字符的字符串类型，可转换为数值类型。
• 字符串 → 日期：传入包含有效格式日期值的字符串类型，并在解析器(Parser)字段中选择对应的日期格式。例如，若传入值为06/26/24的字符串变量，选择M/dd/yyyy作为对应的解析器格式，即可转换为日期类型。
• 字符串 → 时间戳：传入包含有效格式时间戳值的字符串类型，并在解析器(Parser)字段中选择对应的时间戳格式。转换输出时间戳值时使用的时区，可通过用户本地时区定义、通过下拉选项静态设置，或通过字符串引用或变量动态设置。例如，若传入值为2024 06 26 12:50 AM的字符串变量，选择yyyy M dd hh:mm aa作为对应的解析器格式，即可转换为时间戳类型。
• 字符串 → 地理点：传入格式为[纬度], [经度]对的字符串类型，可转换为地理点类型。例如：40.782142,-73.96596。
• 字符串 → 地理形状：传入以 JSON 格式包含形状类型和坐标数组的字符串类型，可转换为地理形状类型。例如：{"type":"Polygon","coordinates":[[[-73.9580917968885,40.80044406792189],[-73.98186087075722,40.76811683550534],[-73.97304465743831,40.76434392565562],[-73.94930767833077,40.79687062648023],[-73.9580917968885,40.80044406792189]]]}。
• 时间戳 → 日期：传入时间戳类型，可转换为日期类型。转换输出日期值时使用的时区，可通过用户本地时区定义、通过下拉选项静态设置，或通过字符串引用或变量动态设置。输入的时间戳将根据指定时区的绝对时间戳转换为日期。
• 日期 → 时间戳：传入日期类型，可转换为时间戳类型。转换输出日期值时使用的时区，可通过用户本地时区定义、通过下拉选项静态设置，或通过字符串引用或变量动态设置。输入的日期将转换为表示指定时区当日开始时间的时间戳。
• 任意类型 → 字符串：任何原始类型转换为字符串，均可使用字符串拼接(String concatenation)操作完成。

对象集转换(Object set transforms)

• 为空(Is empty)： 对给定对象集中是否存在对象执行布尔检查。
• 不为空(Is not empty)： 对给定对象集中是否存在对象执行布尔检查。
• 对象属性(Object property)： 根据单个对象及该对象类型的指定属性，返回属性值。
• 对象集聚合(Object set aggregation)： 对给定对象集的指定属性执行聚合操作。支持的聚合包括最小值、最大值、总和、平均值和基数。
• 对象 RID(Object RID)： 返回给定对象的对象 RID。

数学运算(Math operations)

• 加法(Add)： 返回给定数值或变量之和。
• 减法(Subtract)： 返回给定数值或变量之差。
• 乘法(Multiply)： 返回给定数值或变量之积。
• 除法(Divide)： 返回给定数值或变量之商。
• 绝对值(Absolute)： 返回给定数值或变量的绝对值。
• 取反(Negate)： 返回给定数值或变量的相反数。
• 向上取整(Round Up / Ceil)： 将给定数值或变量按指定精度向上取整。
• 向下取整(Round Down / Floor)： 将给定数值或变量按指定精度向下取整。
• 四舍五入(Round Nearest)： 将给定数值或变量按指定精度四舍五入。
• 最大值(Max)： 从一组数值、日期或时间戳值或变量中返回最大值。
• 最小值(Min)： 从一组数值、日期或时间戳值或变量中返回最小值。

日期/时间运算(Date/time math)

• 相对日期(Relative date)： 根据给定的数值或变量（指定要增加或减少的天数、周数、月数或年数）以及日期值或变量，返回计算后的日期。
• 相对时间(Relative time)： 根据给定的数值（指定要增加或减少的秒数、分钟数、小时数、天数、周数、月数或年数）以及时间值或变量，返回计算后的时间。
• 日期差(Between dates)： 返回两个给定日期值或变量之间的数值差。返回的差值可按天、周、月或年计算。
• 时间差(Between times)： 返回两个给定时间值或变量之间的数值差。返回的差值可按秒、分钟、小时、天、周、月或年计算。
• 当前日期(Current date)： 返回当前日期。

日期比较(Date comparisons)

• 不早于(Is on or after)： 对第一个给定日期值或变量是否不早于第二个给定日期值或变量执行布尔检查。
• 晚于(Is after)： 对第一个给定日期值或变量是否晚于第二个给定日期值或变量执行布尔检查。
• 不晚于(Is on or before)： 对第一个给定日期值或变量是否不晚于第二个给定日期值或变量执行布尔检查。
• 早于(Is before)： 对第一个给定日期值或变量是否早于第二个给定日期值或变量执行布尔检查。
• 等于(Is equal)： 比较两个给定日期值或变量是否相等，执行布尔检查。

时间比较(Time comparisons)

• 不早于(Is on or after)： 对第一个给定时间值或变量是否不早于第二个给定时间值或变量执行布尔检查。
• 晚于(Is after)： 对第一个给定时间值或变量是否晚于第二个给定时间值或变量执行布尔检查。
• 不晚于(Is on or before)： 对第一个给定时间值或变量是否不晚于第二个给定时间值或变量执行布尔检查。
• 早于(Is before)： 对第一个给定时间值或变量是否早于第二个给定时间值或变量执行布尔检查。
• 等于(Is equal)： 比较两个给定时间值或变量是否相等，执行布尔检查。

数值比较(Numeric comparisons)

• 等于(Equal to)： 比较给定数值或变量是否相等，执行布尔检查。
• 不等于(Not equal to)： 比较给定数值或变量是否不相等，执行布尔检查。
• 小于(Less than)： 对第一个给定数值或变量是否小于第二个给定数值或变量执行布尔检查。
• 小于或等于(Less than or equal to)： 对第一个给定数值或变量是否小于或等于第二个给定数值或变量执行布尔检查。
• 大于(Greater than)： 对第一个给定数值或变量是否大于第二个给定数值或变量执行布尔检查。
• 大于或等于(Greater than or equal to)： 对第一个给定数值或变量是否大于或等于第二个给定数值或变量执行布尔检查。

字符串比较(String comparison)

• 等于(Is)： 比较给定字符串值或变量是否相等，执行布尔检查。
• 不等于(Is not)： 比较给定字符串值或变量是否不相等，执行布尔检查。
• 包含(Contains)： 对第二个给定字符串值或变量是否为第一个给定字符串值或变量的子串执行布尔检查。
• 不包含(Does not contain)： 对第二个给定字符串值或变量是否为第一个给定字符串值或变量的子串执行布尔检查。
• 以...开头(Starts with)： 对第二个给定字符串值或变量是否为第一个给定字符串值或变量的前缀执行布尔检查。
• 以...结尾(Ends with)： 对第二个给定字符串值或变量是否为第一个给定字符串值或变量的后缀执行布尔检查。

布尔比较(Boolean comparisons)

• 为真(Is true)： 对给定布尔变量是否为真执行布尔检查。
• 为假(Is false / NOT)： 对给定布尔变量是否为假执行布尔检查。
• 为空(Is null)： 对给定变量是否为空执行布尔检查。
• 不为空(Is not null)： 对给定变量是否不为空执行布尔检查。

地理空间(Geospatial)

• 从地理点获取地理哈希(Geohash from geopoint)： 将给定的地理点转换为字符串形式的地理哈希值。
• 从地理点获取纬度(Latitude from geopoint)： 从给定的地理点返回数值形式的纬度值。
• 从地理点获取经度(Longitude from geopoint)： 从给定的地理点返回数值形式的经度值。
• 从地理点获取 MGRS(MGRS from geopoint)： 将给定的地理点转换为字符串形式的 MGRS 值。

数组操作(Array operations)

• 组合(Compose)： 返回包含所有给定数组中所有值的数组。
• 交集(Intersection)： 返回仅包含给定数组之间共有值的数组。
• 更新指定元素(Update element at)： 返回一个数组，其中给定数组中的特定元素已被更新。构建者可通过指定代表元素在数组中位置的索引来标识要更新的元素。
• 获取指定元素(Get element at)： 返回与给定数组中指定索引处元素对应的值，且该值与数组类型匹配。
• 长度(Length)： 返回代表给定数组中元素数量的数值。

数组检查(Array checks)

• 包含(Contains)： 对给定数组中是否存在给定值执行布尔检查。
• 不包含(Does not contain)： 对给定数组中是否不存在给定值执行布尔检查。
• 是子集(Is subset of)： 对给定数组是否为另一个给定数组的子集执行布尔检查。
• 为空(Is null)： 对给定数组是否为空执行布尔检查。
• 注意：如果为值选择了数组变量引用，此转换将评估并显示为"为空(is empty)"。
• 不为空(Is not null)： 对给定数组是否不为空执行布尔检查。
• 注意：如果为值选择了数组变量引用，此转换将评估并显示为"不为空(is not empty)"。

结构体转换(Struct transforms)

• 提取结构体字段(Extract struct field)： 根据给定的结构体和字段 ID，返回结构体字段值。更多详情请参见从结构体中提取字段(Extract a field from a struct)。