When working with expressions in Spotfire, users often encounter two ways to reference document property values: DocumentProperty("propertyname") and ${propertyname}. While both can return a value, their underlying mechanisms differ significantly, leading to varying behaviors, especially when dealing with numerical comparisons.

• DocumentProperty() function: This is a standard function call that undergoes type checking during the expression parsing phase. If you use an integer property in a context expecting an integer, it will be type-checked, and errors will be reported if the usage is incorrect. The actual value is retrieved at query execution time.
• ${propertyname} preprocessor syntax: This acts as a pure text replacement that occurs before the expression is parsed. The content of the document property is literally inserted into the expression string. The entire expression, with the text replacement, is then parsed. This allows for building complex expressions where individual parts might be invalid, but the combined expression becomes valid. However, a significant drawback is that it disables automatic adaptation to column name changes, potentially invalidating plots.

For example, in an expression like x < ${OilSeg1}, if OilSeg1 is a document property with a value of 5, the preprocessor replaces ${OilSeg1} with 5, resulting in x < 5. The Spotfire parser then interprets 5 as an integer. This explains why an "insert as text" approach can still function correctly for numerical comparisons, even though the initial action is a text replacement. The expression works as intended because the resulting string is a valid numerical comparison.

Guidelines

To ensure robust error checking and better maintainability of Spotfire expressions, it is recommended to use the DocumentProperty() method as the primary choice for incorporating document property values.

1. Prioritize DocumentProperty(): For cases where a document property's value (e.g., an integer or a number) is expected in an expression, use DocumentProperty("PropertyName").
   This allows for proper type checking during expression parsing and provides clearer error messages if the property's type or usage is incorrect.
   
• Example: Instead of x < ${OilSeg1}, use x < DocumentProperty("OilSeg1").
  
  
2. Use ${propertyname} only when necessary: The preprocessor syntax ${propertyname} should be reserved for scenarios where you genuinely need to build a dynamic expression by inserting text that might represent a column name, a measure, or a complex part of the expression that cannot be handled by a function call.
   Be aware of the limitations, such as the lack of automatic adaptation to column name changes.

By following these guidelines, you can leverage the power of document properties in Spotfire expressions while ensuring better expression validity and easier troubleshooting.

All

This article clarifies the difference between using DocumentProperty() and ${propertyname} in Spotfire expressions, explaining why the latter might work unexpectedly when a numerical value is intended despite being a text replacement.

• Why is my insert as text being processed as a number/value?
• Properties in expressions