Validation Rules#
A compile checks the definitions with MetricFlow's 28 validation rules, then with the Hopsworks rules, which bind them to feature groups and plan every metric. Each problem is an issue with a level, a rule, the file, line and column, and the element, as Compile and builds shows. An ERROR makes the build INVALID, so the last valid build keeps answering queries; a WARNING does not.
MetricFlow rules#
The rules of MetricFlow's default validator, in its order, with the RULE their issues carry. Every issue is an ERROR unless the table says WARNING.
| MetricFlow rule | RULE | Reports |
|---|---|---|
| PercentileAggregationRule | PERCENTILE | A percentile measure without agg_params.percentile, or with one that is not strictly between 0 and 1; a median measure with another percentile or use_discrete_percentile; percentile parameters on another aggregation. |
| DerivedMetricRule | DERIVED_METRIC | An alias used by two inputs, an input with both offset_window and offset_to_grain, a custom granularity in offset_to_grain; a WARNING for an input that expr does not use. |
| CountAggregationExprRule | COUNT_EXPR | A count measure without expr, or whose expr starts with distinct; use count_distinct for that. |
| SemanticModelMeasuresUniqueRule | UNIQUE_NAMES | A measure name defined in two semantic models. |
| SemanticModelValidityWindowRule | VALIDITY_WINDOW | Validity parameters other than one is_start and one is_end time dimension; a validity window without a natural entity, with a primary or unique entity, or with measures. |
| DimensionConsistencyRule | DIMENSION_CONSISTENCY | A dimension name with another type, or another is_partition, in another semantic model. |
| ElementConsistencyRule | ELEMENT_CONSISTENCY | A name that is a measure, a dimension or an entity in one semantic model and another kind of element in another. |
| NaturalEntityConfigurationRule | NATURAL_ENTITY | More than one natural entity in a semantic model, or one without a validity window. |
| MeasureConstraintAliasesRule | MEASURE_ALIAS | A metric that reads differently filtered versions of a measure without aliasing them; an alias that names a measure, or that another metric uses. |
| MetricMeasuresRule | REFERENCE | A metric that reads a measure no semantic model defines. |
| CumulativeMetricRule | CUMULATIVE_METRIC | Both window and grain_to_date; a window given twice with different values; a custom granularity in window or grain_to_date; an input metric that is not simple. A WARNING for both a measure and a metric as input. |
| NonEmptyRule | EMPTY | No semantic models; a WARNING for no metrics. |
| UniqueAndValidNameRule | NAMING, UNIQUE_NAMES | A name that is not lower case letters, digits and underscores starting with a letter, is shorter than two characters, ends with _, contains __, is a granularity or is metric_time; a name defined twice; two elements of a semantic model with one name; a custom granularity with the name of another element. |
| AggregationTimeDimensionRule | AGG_TIME_DIMENSION | A measure without an agg time dimension, declared or from the event time of its feature group, or with one that is not a time dimension of its semantic model. |
| ReservedKeywordsRule | RESERVED_KEYWORD | An entity, dimension or measure, or a part of a node_relation, named with an SQL reserved keyword, such as select or from. |
| MeasuresNonAdditiveDimensionRule | NON_ADDITIVE_DIMENSION | A non_additive_dimension that is not a time dimension of the semantic model, or not at the granularity of the measure's agg time dimension; window_groupings that are not entities of the semantic model. |
| SemanticModelDefaultsRule | AGG_TIME_DIMENSION | A defaults.agg_time_dimension that is not a time dimension of the semantic model. |
| PrimaryEntityRule | PRIMARY_ENTITY | Two primary entities; an entity of type primary and primary_entity both; dimensions without a primary entity. |
| PrimaryEntityDimensionPairs | PRIMARY_ENTITY_DIMENSION | Two semantic models with the same primary entity and a dimension of the same name, which one group-by name would reach in both. |
| WhereFiltersAreParseable | WHERE_FILTER | A filter of a metric, an input or a saved query that does not parse. A WARNING for a filter that names an unknown granularity, or one that cannot be applied. |
| SavedQueryRule | SAVED_QUERY | A saved query metric that does not exist; a group-by that does not parse or is not a metric, metric_time, a dimension or an entity; an order-by that is none of its metrics and group-bys; a negative limit. |
| MetricLabelsRule | LABELS | Two metrics with the same label. |
| SemanticModelLabelsRule | LABELS | Two semantic models with the same label; two dimensions, entities or measures of a semantic model with the same label. |
| EntityLabelsRule | LABELS | An entity with different labels in different semantic models. |
| ConversionMetricRule | CONVERSION_METRIC | An entity that is not an entity of both semantic models; an input that does not aggregate with count, count_distinct or sum of 1; a constant property that is not a dimension or entity of its semantic model; a custom granularity in window; an input metric that is not simple. A WARNING for a filter on the conversion input, and for both a measure and a metric as input. |
| TimeSpineRule | TIME_SPINE | Only WARNINGs, with a time spine declared: two time spines of one granularity, no time dimensions, or a finest time spine coarser than the finest agg time dimension of the measures. |
| TimeDimensionHasGranularityRule | TIME_DIMENSION | A time dimension without type_params.time_granularity. |
| SimpleMetricExprRule | SIMPLE_METRIC_EXPR | A WARNING for a simple metric that reads a measure and sets an expr of its own, which is ignored. |
Hopsworks rules#
RULE | Level | Reports |
|---|---|---|
TOO_MANY_FILES, FILE_TOO_LARGE, FILES_TOO_LARGE | ERROR | More than 1000 files under the root path, a file over 1 MiB, or files over 32 MiB in all, see Project layout. |
TOO_MANY | ERROR | More elements of one kind than a semantic project may define, see Limits, at the first element over the limit; nothing after it is read. |
TOO_MANY_ISSUES | ERROR, WARNING | More than 1,000 errors or 1,000 warnings: the first 1,000 of each are listed, then one issue says how many more were found. An ERROR also when the issues take more room than a build stores, 4 MiB; the leading issues are kept and the build is INVALID. |
ANSWER_TOO_LARGE | ERROR | The compile's answer, which holds the definition files and every issue found in them, is larger than 64 MiB, or 8 MiB for the editor's validation. Fix the definitions that repeat an error, or split them over more than one semantic project. |
YAML_SYNTAX | ERROR | A file that does not parse as YAML or JSON. |
YAML_DUPLICATE_KEY | WARNING | A key twice in one mapping; the last value is used. |
UNKNOWN_KEY | WARNING | A top-level key the format does not define. |
REQUIRED | ERROR | A required key left out, such as a metric's type or a simple metric's measure. |
TYPE | ERROR | A value of the wrong type, or an unknown aggregation, granularity, entity type, metric type or window. |
MODEL_REF | ERROR | A model that is not ref('<name>'), or a semantic model with none of model, node_relation and config.meta.hopsworks.feature_group. |
FILTER | ERROR | A filter that is neither a string nor a list of strings. |
REFERENCE | ERROR | A metric, measure or semantic model a definition names and none defines. |
PHASE | ERROR | agg on the metric itself, dbt's newer YAML spec; a metric without a measure takes type_params.metric_aggregation_params. |
METRIC_AGGREGATION_PARAMS | WARNING | A simple metric with both metric_aggregation_params and a measure; the measure is ignored. |
CYCLE | ERROR | Metrics that read each other in a cycle. |
METRIC_TREE | ERROR | A metric that reads through more than 32 levels of input metrics, or expands to more than 1,000 metric references. |
RELATION | ERROR | A semantic model whose feature group does not exist, or is in a feature store neither the project's nor shared with it. |
EXPR | ERROR | An expr that does not compile against the feature group's features, such as a feature name with a typo. |
TIME_DIMENSION | ERROR | A time dimension whose feature is not a date or a timestamp. |
EVENT_TIME | WARNING | A feature group event time that cannot be linked to a time dimension of a semantic model, see Event time. |
TIME_SPINE | ERROR | A metric that needs a time spine none is bound for, see Without a time spine. A WARNING for a declared time spine that does not bind. |
METRIC | ERROR | A metric that the planner cannot plan, with the planner's reason, such as an exact percentile on Trino. |
SAVED_QUERY | ERROR | A saved query that the planner cannot plan, with the planner's reason. |
NAME_TOO_LONG | ERROR | A metric or saved query name longer than 255 characters. |
EXPORTS_TOO_LARGE | ERROR | A saved query whose exports take more characters as JSON than are stored; move some of them to another saved query. |
COMPILE_FAILED | ERROR | The compile stopped without recording why, for example because its Payara instance restarted; compile again. |
UNSUPPORTED | WARNING | A metric or saved query of a shape the planner refuses, see Limits; its queries are refused, and the build serves the others. |
METRIC_TAGS_NOT_A_MAP, METRIC_TAG_UNKNOWN_SCHEMA, METRIC_TAG_INVALID_VALUE, METRIC_TAG_MANDATORY_MISSING | ERROR | A metric's tags, see Tag a metric. |
SAVED_QUERY_TAGS_NOT_A_MAP, SAVED_QUERY_TAG_UNKNOWN_SCHEMA, SAVED_QUERY_TAG_INVALID_VALUE | ERROR | A saved query's tags, checked as a metric's are. |
EXPORT_NAME | ERROR | An export name that is not a feature group name, lower case letters, digits and underscores starting with a letter and at most 63 characters, or that two saved queries define. |
EXPORT_AS | ERROR | An export without export_as, or with export_as: view or anything but table. |
EXPORT_TARGET | ERROR | An export's feature group name, its alias or else its name, that is not a valid feature group name or that two exports write; a version below 1. A WARNING for a schema, which is not used. |
EXPORT_SCHEDULE | ERROR | A schedule that is not a Quartz cron expression, is longer than 255 characters, or does not have 0 as its seconds field. |
EXPORT_LOOKBACK | ERROR | A lookback that is not <count> <granularity> with a count of at least 1, such as 7 days, or an export with a lookback whose saved query does not group by metric_time at a grain. |
EXPORT_KEYS | ERROR | An export of a saved query without group-bys. |
EXPORT_SETTINGS | ERROR | A config.meta.hopsworks.exports that does not map export names to settings, or that names an export the saved query does not have. |
EXPORT_SERVING | WARNING | A saved query with exports whose rows can depend on when it runs, through CURRENT_DATE, now() or a function the compiler does not know, such as a UDF, in a filter or expression: its exports are refreshed, and never answer queries. |
The EXPORT_* rules check the metric exports of saved queries.
Limits#
A semantic project defines at most, over all its files:
| Element | Most |
|---|---|
| Semantic models | 1,000 |
| Entities | 10,000 |
| Dimensions | 20,000 |
| Measures | 10,000 |
| Metrics | 10,000 |
| Saved queries | 1,000 |
| Exports | 1,000 |
| Time spines | 100 |
The first element over a limit is a TOO_MANY error at its file and line, and the compile reads nothing after it. A compile lists at most 1,000 errors and 1,000 warnings, and stops once it has found more than 1,000 errors; a build's error and warning counts count every issue found, and can be larger than the list. The files under the root path are limited too, see Project layout.
hops semantic build <name> <id>, SemanticProject.get_build(id).issues and View issues on the Builds card list a build's issues.