Elements of Lens

The Lens is composed of elements such as fields, entities, dimensions, and measures. The objective of these elements is to define the structure and logic of data models. They introduce opinionated simplicity in explaining the reasoning for business concepts.

Entities

Entities are logical representations of an organization’s widely referred to and analyzed business concepts. They describe business objects such as customers, products, and users or business-specific activities such as web and app events, downloads, and purchases.

Apart from the name and description of an entity, entity declaration within a Lens defines the following properties.

Properties	Description	Requirement
sql	A query that runs against your data source to extract the entity table	Mandatory
field	Unique identifiers for an entity	Optional
dimension	Categorical or time-based data that helps in adding context to the measures	Optional
measures	Aggregated columns are calculated using SQL expressions. Measures are the foundation for defining metrics.	Optional
relationship	Defines the relationship of entities with other entities. An entity can be joined to other entities and have one-to-one, one-to-many, or many-to-one relationships.	Optional
extend	This allows you to extend an existing entity to use all declared elements of the entity.	Optional

To learn more about entities, refer to Entity

Field

Field, Dimensions, Measures, and Relationships are integral to the schema of all entities you define.

Fields are columns that uniquely identify an entity. The fields contain direct mapping to the underlying data source columns. Mention all the columns in the field that directly map to your underlying table.

Supported properties by fields

Properties	Description	Requirement
name	Name of the field	Optional
type	Type of the field	Mandatory
description	Description of the field	Optional
column	Maps your field to the column in the physical table	Optional
primary	Use this property to explicitly state whether the field needs to be considered a primary key.	Optional

To know more about fields, refer to Fields.

Dimensions

The Lens dimensions are columns containing qualitative data; they are groupable and can be used to query measures to varying levels of granularity.

Dimensions can be -

• An attribute that can directly reference a column of the underlying table, or
• A derived value calculated using a SQL expression

For instance, dimensions for a Customer entity might include first name, last name, email, phone, location, and age.

Supported properties for dimensions

Properties	Description	Mandatory/Optional
name	Name of the dimension.	Optional
description	Description of the dimension.	Optional
type	Type of the dimension.	Mandatory
sql_snippet	A query to extract dimensions from the physical table. It can either be a one-to-one mapping to a column of your physical table, or you can define a custom query.	Optional
sub_query	Allows referencing measures from other entities. It’s of boolean type.	Optional
hidden	It will hide the dimension from the user interface if set to true.	Optional

To know more about dimensions, refer to Dimensions.

Measures

Measures are aggregated numerical values derived from quantitative columns. You can also define complex expressions in the SQL snippet besides using the supported aggregation types. A measure can be referenced within a measure to achieve the desired aggregation.

For instance, Orders Entity might include measures such as quantities sold (count), total order amount(sum), and average order amount (avg).

Supported properties for measures

Properties	Description	Requirement
name	Name of the measure	Optional
description	Description of the measure	Optional
type	Type of the measure.	Yes
sql_snippet	Based on the measure(aggregation) type, you can specify the aggregated column or define a custom query.	Optional
rolling_window	You can aggregate column values within a defined window, just like the SQL window function.	Optional
hidden	It will hide the dimension from the user interface if set to true.	Optional

To know more about measures, refer to Measures.

Relationships

It defines the relationship between two entities; it can be - one-to-one, one-to-many, or many-to-one. A defined relationship simplifies querying dimensions and measures from multiple entities. Entities would be joined based on the defined keys and relationships. Once the relationship and fields are declared in the model, Lens will automatically generate join logic to render columns correctly.

Supported properties for relationships

Properties	Sub-Property	Description	Requirement
field		The field on which the join will be defined. Its ‘primary’ property is set to true (Primary Key)	Mandatory
target			Mandatory
	name	The entity you need to join.
	field	Join will be performed using this field of the entity
description			Optional
type		Type of the relationship - 1:1,1:N,N:1	Mandatory
sql_snippet		If you have more than one clause in your join statement, you can add a query for it.	Optional

To learn more about relationships, refer to Relationships.