The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
Construct Query Reference
Construct a Metabase MBQL 5 query as a JSON object describing the query shape. Metabase validates, repairs, and resolves it.
Return:
query: a JSON object (never a quoted string). The target database is inferred from the first stage'ssource-table(orsource-card) — use the exact database name reported by search /read_resource/ metadata tools.title: required short, human-friendly title for the resulting chart, shown above it (e.g."Orders by month").description: required concise one- or two-sentence description of what the chart shows (the metric, the grouping, and any notable filter); it is used as the saved question's description.visualization: optional{"chart_type": "bar"}(sibling ofquery, never embedded inside it).
Minimal example — count of orders by month
{"lib/type": "mbql/query",
"stages": [{"lib/type": "mbql.stage/mbql",
"source-table": ["Sample Database", null, "ORDERS"],
"aggregation": [["count", {}]],
"breakout": [["field", {"temporal-unit": "month"},
["Sample Database", null, "ORDERS", "CREATED_AT"]]]}]}
Every clause is ["op", {}, ...args] with a mandatory {} options map at position 1; every field reference uses a 4-segment portable FK in the last slot. These are the two most-violated rules.
Universal clause shape
Every operation is ["<operator>", {options}, ...args]. The options map is always present, even when empty.
- Good:
["count", {}],["field", {}, ["DB", "SCH", "TBL", "COL"]],["sum", {}, <expr>] - Bad:
["count"],["field", ["DB", "SCH", "TBL", "COL"]]
The pipeline repairs missing {} slots, but write them — your output should match what later inspection will show.
Top-level query and stage shape
Top level:
"lib/type": "mbql/query"— required marker."stages": [...]— at least one stage.
Stage ("lib/type": "mbql.stage/mbql" — required marker):
source-tableorsource-card— exactly one, first stage only. Later stages take the previous stage's output implicitly.- Optional:
filters,aggregation,breakout,expressions,fields,joins,order-by,limit,page.
There is no top-level database: field in the LLM contract — the database is derived from the source.
Field references
["field", {}, ["<db-name>", "<schema-or-null>", "<table-name>", "<field-name>"]]
The third slot is the portable field FK — a 4+ element string array. Schemaless databases (the Sample Database, MongoDB, etc.) use null in the schema slot: ["Mongo", null, "orders", "created_at"]. JSON-unfolded fields append extra segments: ["DB", "SCH", "TBL", "PARENT", "CHILD"].
Inside later stages, refer to a column produced by the previous stage by string name instead of a portable FK: ["field", {}, "count"], ["field", {}, "PRODUCT_ID"].
Field options (all optional):
temporal-unit— bucket a date/time field, e.g."month","day","hour". Full list in §Operator catalogs.join-alias— required on every field reference that lives inside an explicit join.source-field— portable FK of the FK column on the source table; only needed when the implicit-join auto-fill is ambiguous.source-field-name— name of the FK column when it comes from a previous stage's output (rare; not auto-filled).source-field-join-alias— explicit-join alias the FK column belongs to (usually auto-filled).binning— bucket a numeric field.
base-type is auto-filled on cross-stage refs — don't write it.
Per-clause examples
Use one entry per filter condition. Metabase combines the entries with and.
"filters": [[">", {}, ["field", {}, ["Sample Database", null, "ORDERS", "TOTAL"]], 100],
["<=", {}, ["field", {}, ["Sample Database", null, "ORDERS", "QUANTITY"]], 5]]
Use one entry for conditions combined with or or negated together by not; nest and inside them when needed. For example, "total over 100, or quantity at most 5":
"filters": [["or", {},
[">", {}, ["field", {}, ["Sample Database", null, "ORDERS", "TOTAL"]], 100],
["<=", {}, ["field", {}, ["Sample Database", null, "ORDERS", "QUANTITY"]], 5]]]
Aggregation (on a field, plus count):
"aggregation": [["sum", {}, ["field", {}, ["Sample Database", null, "ORDERS", "TOTAL"]]],
["count", {}]]
Breakout with temporal bucket:
"breakout": [["field", {"temporal-unit": "month"},
["Sample Database", null, "ORDERS", "CREATED_AT"]]]
Order by — direction wraps a ref; works on field refs or aggregation refs:
"order-by": [["desc", {}, ["field", {}, ["Sample Database", null, "ORDERS", "CREATED_AT"]]],
["desc", {}, ["aggregation", {}, 0]]]
"limit": 50 and "fields": [<field-ref>, ...] are the obvious scalar / list forms.
Aggregation references
To refer to an aggregation already in the same stage's aggregation list — e.g. from order-by:
- Inline — repeat the clause itself. The inline form must match an entry in
aggregationexactly (same op, same args). The tool rewrites it to a reference. - By 0-based index (preferred when reused) —
["aggregation", {}, 0]means "the first aggregation".
Out-of-range indices surface a clear error listing every available aggregation with its index.
Expressions
Define custom columns inside a stage using expressions and reference by name with ["expression", {}, "<Name>"]. Object form (preferred); the name becomes the column's display name.
"expressions": {
"Subtotal": ["+", {},
["field", {}, ["Sample Database", null, "ORDERS", "TOTAL"]],
["field", {}, ["Sample Database", null, "ORDERS", "TAX"]]]
},
"aggregation": [["sum", {}, ["expression", {}, "Subtotal"]]]
The sequential form [["expression", {}, "Name", expr], ...] is also accepted and auto-converted.
Joins (explicit)
"joins": [{
"alias": "Products",
"strategy": "left-join",
"stages": [{"lib/type": "mbql.stage/mbql",
"source-table": ["Sample Database", null, "PRODUCTS"]}],
"conditions": [["=", {},
["field", {}, ["Sample Database", null, "ORDERS", "PRODUCT_ID"]],
["field", {"join-alias": "Products"},
["Sample Database", null, "PRODUCTS", "ID"]]]]
}],
"breakout": [["field", {"join-alias": "Products"},
["Sample Database", null, "PRODUCTS", "CATEGORY"]]]
aliasis a free-choice string; use it consistently in conditions, breakout, aggregation, order-by.strategyis one of"left-join","right-join","inner-join","full-join". Default"left-join".- Every field reference on the joined side must carry
{"join-alias": "<same-alias>"}. - Join
conditionsaccept only=,!=,<,<=,>,>=— nobetween,in,and/orwrappers.
Implicit joins
Reference a field on a related table directly — when the source has exactly one FK to that target, the tool auto-fills source-field and performs the implicit join:
"source-table": ["Sample Database", null, "ORDERS"],
"aggregation": [["count", {}]],
"breakout": [["field", {}, ["Sample Database", null, "PRODUCTS", "CATEGORY"]]]
- If the error says the field is reachable through several foreign keys, list the source table's fields and retry with explicit
{"source-field": ["DB", "SCH", "SRC", "FK_COL"]}on the field to select the intended FK. - No FK path →
:no-fk-path. Switch to an explicitjoinsentry, or pick a field on the source table. - Inside an explicit
joinsblock, joined-side field refs still need{"join-alias": ...}— implicit-join repair does not rewrite those. - If the FK column lives on a previous stage's output, write
{"source-field-name": "<col>"}(not auto-filled). - If multiple explicit joins all expose the target FK,
:ambiguous-fk-via-joinlists them — set{"source-field-join-alias": "<alias>"}to pick one.
Tip: discover FKs with read_resource metabase://table/<id>/fields. FK columns are tagged fk_target_fully_qualified_name="schema.table.field" — always look for one before assuming a column lives on the current table.
Multi-stage queries
Every stage after the first consumes the previous stage's output. Only the first stage has a source-table/source-card; later stages omit it.
Post-aggregation filter — count orders per product, keep only those with > 10:
"stages": [
{"lib/type": "mbql.stage/mbql",
"source-table": ["Sample Database", null, "ORDERS"],
"aggregation": [["count", {}]],
"breakout": [["field", {}, ["Sample Database", null, "ORDERS", "PRODUCT_ID"]]]},
{"lib/type": "mbql.stage/mbql",
"filters": [[">", {}, ["field", {}, "count"], 10]]}
]
Re-aggregate — average daily total by month:
"stages": [
{"lib/type": "mbql.stage/mbql",
"source-table": ["Sample Database", null, "ORDERS"],
"aggregation": [["sum", {}, ["field", {}, ["Sample Database", null, "ORDERS", "TOTAL"]]]],
"breakout": [["field", {"temporal-unit": "day"},
["Sample Database", null, "ORDERS", "CREATED_AT"]]]},
{"lib/type": "mbql.stage/mbql",
"aggregation": [["avg", {}, ["field", {}, "sum"]]],
"breakout": [["field", {"temporal-unit": "month"}, ["field", {}, "CREATED_AT"]]]}
]
- Cross-stage refs use a string name in slot 3 (e.g.
["field", {}, "count"]). The name is the previous stage column's machine name, never its UI display label:- An aggregation's output name is the bare function:
max,min,avg,sum,count,median— the operand is dropped.["max", {}, ["expression", {}, "Instance Has SC"]]produces a column namedmax(display label "Max of Instance Has SC"). Reference it as["field", {}, "max"], not["field", {}, "Max of Instance Has SC"]. - A breakout keeps the source field's machine name even when its label is bucketed: a month breakout of
CREATED_ATis still namedCREATED_AT(display "Created At: Month"). - If a stage has several aggregations of the same function, the outputs are suffixed in order:
max,max_2,max_3. So the secondmaxis referenced as["field", {}, "max_2"].
- An aggregation's output name is the bare function:
- A
["field", {}, "<name>"]cross-stage ref whose name matches no column the previous stage produced is an error — name it exactly. - Within the same stage, refer to your own aggregation with
["aggregation", {}, <idx>](see §Aggregation references). In a later stage, use the cross-stage string-name form against the previous stage's output. - Joins, expressions, filters, aggregation, breakout, order-by, limit are all valid in later stages.
Saved questions and models (source-card)
Instead of source-table, use source-card to query an existing question or model. The value is the card's portable entity id — a 21-char opaque string reported by search and read_resource as portable_entity_id.
- Get the
portable_entity_idfrom a tool response.searchandread_resource(metabase://question/<id>,metabase://model/<id>) include it on the result tag — reuse what's already in context, no extra call needed. - Copy it verbatim into
source-card. The id is opaque — never guess, construct, or abbreviate. - Reference the card's columns by output machine name (string in slot 3), not portable FK and not the UI display label. If you don't know the names, call
read_resource metabase://question/<numeric-id>/fields(or.../model/...) — a ref whose name matches no column the card produces is an error.
{"lib/type": "mbql.stage/mbql",
"source-card": "T4wA_GPFwGb6R4FxIDGTo",
"filters": [[">", {}, ["field", {}, "total"], 100]],
"limit": 50}
A stage has either source-table or source-card, never both. The card must live in the same database as the rest of the query (no cross-database queries). Falling back to native SQL like SELECT * FROM {{#<id>-<slug>}} is not acceptable — always use source-card.
Metrics
A metric is a predefined aggregation. Its <metric> tag identifies the source to use: a base table, saved question or model. Build the stage on that source. The tag carries at most one of these attributes:
base_table_fully_qualified_namenames a base table. Combine it withdatabase_nameto form the portable FK forsource-table.source_card_portable_entity_idnames a saved question or model. Copy the ID verbatim intosource-card.source_unavailable="true"means that the metric has no source available to you. Do not use it.
To use a metric:
- Copy the source attribute into the stage. Never invent schema or table names, or substitute a base table for the source card. If the tag carries
source_unavailable="true", or carries neither source attribute, do not use the metric or guess its source. Say that the metric is not available to you and express the aggregation directly instead, or ask which source to use. - Reference the metric as
["metric", {}, "<portable_entity_id>"]inaggregation. - Use dimensions from the metric's Dimensions table for filters and breakouts on the same stage. Read the
Source tablecolumn first. Names such asidandcreated_atcan appear on several tables, and the table determines how to reference a dimension:- Copy
Referenceverbatim for a dimension on the metric's own source. Its portable FK works on card and table stages. - A dimension on an FK-related table can be used in
breakout:when one foreign key reaches that table. This works on asource-tableand asource-cardstage alike. Otherwise, follow the tool's error: add an explicitjoinsentry (see "Joins (explicit)") on the same stage, keep the metric's source, and break out on the field using the join alias. - Use the output machine name for an expression or aggregation column computed by the card. These columns have no portable FK.
- Copy
A table metric with base_table_fully_qualified_name="brex_enriched.fct_cards":
{"lib/type": "mbql.stage/mbql",
"source-table": ["Analytics", "brex_enriched", "fct_cards"],
"filters": [["!=", {}, ["field", {},
["Analytics", "brex_enriched", "fct_cards", "card_status"]], "inactive"]],
"aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
A card metric with source_card_portable_entity_id="T4wA_GPFwGb6R4FxIDGTo":
{"lib/type": "mbql.stage/mbql",
"source-card": "T4wA_GPFwGb6R4FxIDGTo",
"filters": [["!=", {}, ["field", {},
["Analytics", "brex_enriched", "fct_cards", "card_status"]], "inactive"]],
"aggregation": [["metric", {}, "aB3cD4eF5gH6iJ7kL8mN9"]]}
A metric with source_card_portable_entity_id requires that exact card. Substituting its base table causes an Incompatible metric error. Some metrics whose definition starts from a card require a base table instead; their tags carry base_table_fully_qualified_name. Use the attribute provided by the tag.
Metrics are aggregations. Put the metric's own portable_entity_id in its aggregation clause, never in source-table or source-card. The source_card_portable_entity_id identifies its source card and belongs in source-card. Use metabase://metric/<id> URIs to read metadata via read_resource; do not embed them in queries.
Using measures and segments
A measure or segment can be referenced two ways. Prefer the opaque-id clause — it preserves the measure/segment's identity in the rendered notebook (chip with the official name, click-through to the definition, lineage tooling sees the dependency, definition updates propagate).
Preferred — opaque-id clause
Each <measure> and <segment> block on a <table> carries a portable_entity_id="…" attribute (a 21-char NanoID). Copy it verbatim:
"aggregation": [["measure", {}, "<portable_entity_id>"]]
"filters": [["segment", {}, "<portable_entity_id>"]]
The stage's source-table must be the table the measure/segment belongs to (the same <table> block where you saw the <measure> / <segment> element).
Fallback — inline the <definition> body
When you need to compose on top of a measure or segment (add an extra filter the segment doesn't include, breakout an aggregation the measure doesn't have, …), copy the JSON array inside <definition> directly into your stage's aggregation: [...] (measure) or filters: [...] (segment) and add your own clauses alongside. The definition is in the same portable form the tool expects.
Don't
- Never invent a
portable_entity_id— only use the value reported in a tool response. - The matching aggregation-only opaque-id clause is
["metric", {}, "<portable_entity_id>"](for metrics, which live independently of a table — see §Metrics above).
Translating the request
Before the shape rules: map the user's wording to the right clause. These mismatches produce a query that runs cleanly and returns the wrong answer, so they're easy to miss.
- A constraint is a filter, not a breakout. "where/only/with X = Y", "for active cards", "USD transactions only" → a
filtersentry restricting to that value. Reservebreakoutfor grouping language: "by", "per", "for each", "broken down by", "over time". "Open rate where opens are multiple" filters to multiple-opens rows; it does not group by the multiple-opens flag. - Apply every constraint in the request. Each "where/only/for/with" condition the user states must appear as a filter — don't drop one because you already added the aggregation.
- Don't add analysis the user didn't ask for. If the request is only "travel expenses", filter to travel and return the rows; don't tack on an average or count that wasn't requested.
- An explicit date or year is an absolute filter. "in 2024", "for 2024", "between 2024-01-01 and 2024-12-31" → an absolute filter on that range. Use
relative-datetime/time-intervalonly when the user uses relative language ("last year", "past 30 days", "year to date").
Rules and common mistakes
Shape rules:
- Always include
{}options in every clause, even when empty.["count"]is wrong — it must be["count", {}]. - The query is a JSON object, not a string. Send it directly as the
"query"field of the call. - Use the exact database name reported by search /
read_resource(e.g."Sample Database", not"Sample") as the first element of every portable FK. Near-misses surfaceUnknown databaseinstead of silently picking one. Cross-database queries are not supported. - Use portable FKs, not numeric IDs. Schemaless databases use
nullin the schema slot. JSON-unfolded fields append path segments. - Clause heads are lowercase, hyphenated:
"count","sum-where","time-interval","get-day-of-week". Not underscores, not camelCase. - Never invent a
source-cardentity_id. It must be a 21-char string copied verbatim from search /read_resource— no patterns, no numeric ids, nocard__<id>. source-cardcolumns are referenced by output name (string in slot 3), not portable FK.
Editing an existing query (the user asks to change, add, or remove part of the question they're viewing):
- Start from the query shown in context and change only what the user asked for. Copy every other clause unchanged, including filters, breakouts, aggregations, and their order.
- Keep each existing filter as its own
filters:entry. To change one filter, replace just that entry. Never merge it with another filter into anand. The notebook shows a combined filter as one custom expression, so the user sees their untouched filters rewritten.
Anti-hallucination:
- Don't subtract dates with
-. Use["datetime-diff", {}, <left>, <right>, "<unit>"]for the integer count of units between two temporal values. - For multi-value categorical filters, use
in/not-in, not=with a list literal. The tool rewrites the list form, but write canonical:["in", {}, <field>, "a", "b"]. - Extracted quarter values are numbers
1, 2, 3, 4, never strings like"Q1". - Don't breakout on the same underlying field twice in one stage. If you breakout by
{"temporal-unit": "month"}, do not also breakout by the raw field. visualizationis a sibling ofquery, never embedded inside it.- Ordering by an inline aggregation must match an
aggregation:entry exactly (same op, same args). If unsure, use["aggregation", {}, <0-based-idx>]. - Never write
metabase://...URIs assource-tableorsource-cardvalues. Those URIs are forread_resource, not for query sources. - Never write
[aggregate, ...],[filter, ...],[order-by, ...],[breakout, ...],[limit, ...]as clause heads — those are stage container keys, not clauses. Place inner clauses directly inside the stage'saggregation:/filters:/ etc. arrays. - Common typos (
count-if,variance,stddev-pop,count-distinct,dayofweek,hour-of-day,month-of-year,quarter-of-year,temporal-diff,relative-date) are auto-corrected, but write the canonical name (count-where,var,stddev,distinct,get-day-of-week,get-hour,get-month,get-quarter,datetime-diff,relative-datetime) so the tool output matches what later inspection will show.
Operator catalogs
Source of truth:
src/metabase/lib/schema/{aggregation,filter,temporal_bucketing}.cljcandsrc/metabase/lib/schema/expression/*.cljc. If something seems missing here, attempt it — the schema may have grown.
Aggregations
["count", {}]— count all rows. Optional 3rd slot<expr>counts non-NULL.["cum-count", {}]— cumulative count. Optional 3rd slot<expr>.["sum", {}, <num-expr>]["cum-sum", {}, <num-expr>]["avg", {}, <num-expr>]["min", {}, <orderable>]["max", {}, <orderable>]["median", {}, <num-expr>]["percentile", {}, <num-expr>, <0..1>]["distinct", {}, <expr>]— count of distinct non-NULL values.["distinct-where", {}, <expr>, <bool-pred>]["count-where", {}, <bool-pred>]["sum-where", {}, <num-expr>, <bool-pred>]["share", {}, <bool-pred>]— fraction of rows where pred is true.["stddev", {}, <num-expr>]["var", {}, <num-expr>]["metric", {}, "<portable_entity_id>"]references a defined metric. Use the source specified by its<metric>tag:base_table_fully_qualified_nameassource-table, orsource_card_portable_entity_idassource-card.["measure", {}, "<portable_entity_id>"]— reference a defined measure (preferred over inlining its definition). The measure's table must be the stage'ssource-table.
Order-by direction
["asc", {}, <ref>]/["desc", {}, <ref>]— wrap any field ref or aggregation ref.
Filters
Boolean:
["and", {}, <pred>, <pred>, ...]– requires at least 2 arguments. Write plain "A and B" as twofilters:entries; nestandunderorornot.["or", {}, <pred>, <pred>, ...]— min 2 args.["not", {}, <pred>]
Equality (variadic, ≥2 args):
["=", {}, <a>, <b>, ...]["!=", {}, <a>, <b>, ...]["in", {}, <expr>, <v1>, <v2>, ...]["not-in", {}, <expr>, <v1>, <v2>, ...]
Comparison:
["<", {}, <a>, <b>]/["<=", {}, <a>, <b>]/[">", {}, <a>, <b>]/[">=", {}, <a>, <b>]["between", {}, <expr>, <min>, <max>]["inside", {}, <lat-expr>, <lon-expr>, <lat-max>, <lon-min>, <lat-min>, <lon-max>]— lat/lon bounding box.
Nullness / emptiness:
["is-null", {}, <expr>]/["not-null", {}, <expr>]["is-empty", {}, <expr>]/["not-empty", {}, <expr>]— equivalent to is-null OR= ""for strings.
String (accept {"case-sensitive": false} in opts):
["starts-with", {}, <str>, <prefix>]["ends-with", {}, <str>, <suffix>]["contains", {}, <str>, <substring>]["does-not-contain", {}, <str>, <substring>]
Temporal:
["time-interval", {}, <temporal>, <n-or-:current/:last/:next>, "<unit>"]— relative window. Opts may set{"include-current": true}.["during", {}, <temporal>, "<iso-date-or-datetime>", "<unit>"]— value falls within the bucket containing the literal.["relative-time-interval", {}, <temporal>, <value>, "<bucket>", <offset-value>, "<offset-bucket>"]— window offset from now.
Named reference:
["segment", {}, "<portable_entity_id>"]— reference a defined segment (preferred over inlining its definition). The segment's table must be the stage'ssource-table.
Expressions
Arithmetic:
["+", {}, <a>, <b>, ...]/["-", {}, <a>, <b>, ...]/["*", {}, <a>, <b>, ...]/["/", {}, <a>, <b>, ...]["abs", {}, <num>]/["power", {}, <num>, <exp>]/["sqrt", {}, <num>]["exp", {}, <num>]/["log", {}, <num>]["ceil", {}, <num>]/["floor", {}, <num>]/["round", {}, <num>]["integer", {}, <num-or-str>]/["float", {}, <num-or-str>]
String:
["concat", {}, <a>, <b>, ...]["substring", {}, <str>, <start>, <length>]— 1-based start; length is optional.["replace", {}, <str>, <old>, <new>]["regex-match-first", {}, <str>, <regex>]["split-part", {}, <str>, <sep>, <n>]["length", {}, <str>]["trim", {}, <str>]/["ltrim", {}, <str>]/["rtrim", {}, <str>]["upper", {}, <str>]/["lower", {}, <str>]["host", {}, <url>]/["domain", {}, <url>]/["subdomain", {}, <url>]/["path", {}, <url>]["month-name", {}, <int>]/["quarter-name", {}, <int>]/["day-name", {}, <int>]["text", {}, <expr>]/["collate", {}, <str>, <collation>]
Conditional:
["case", {}, [[<pred1>, <expr1>], [<pred2>, <expr2>], ...], <default?>]— alias:if.["coalesce", {}, <a>, <b>, ...]
Temporal:
["datetime-add", {}, <temporal>, <n>, "<unit>"]["datetime-subtract", {}, <temporal>, <n>, "<unit>"]["datetime-diff", {}, <left>, <right>, "<unit>"]—<unit>is one ofsecond, minute, hour, day, week, month, quarter, year.["interval", {}, <n>, "<unit>"]["get-year", {}, <temporal>]/["get-month", {}, <temporal>]/["get-day", {}, <temporal>]/["get-quarter", {}, <temporal>]["get-hour", {}, <temporal>]/["get-minute", {}, <temporal>]/["get-second", {}, <temporal>]["get-week", {}, <temporal>]/["get-day-of-week", {}, <temporal>]— both accept optional 4th-slot mode"iso","us","instance".["temporal-extract", {}, <temporal>, "<unit>"]— extract one of the date/time extraction units listed below.["convert-timezone", {}, <temporal>, "<target-tz>"]— optional 4th slot is source tz.["relative-datetime", {}, <n>, "<unit>"](or["relative-datetime", {}, "current"])["absolute-datetime", {}, "<iso-string>", "<unit?>"]["date", {}, <expr>]/["datetime", {}, <expr>]/["time", {}, <expr>]["now", {}]/["today", {}]
Window:
["offset", {}, <expr>, <n>]— value of<expr>from<n>rows back (negative<n>) or ahead (positive). Valid only inside anaggregation:ororder-by:clause — never in a custom column (expressions:) or a filter.
Temporal units (for {"temporal-unit": ...} on field refs and as <unit> args)
- Date truncation:
day,week,month,quarter,year - Date extraction (integer-returning):
day-of-week,day-of-month,day-of-year,week-of-year,month-of-year,quarter-of-year,year,year-of-era - Time truncation:
millisecond,second,minute,hour - Time extraction (integer-returning):
second-of-minute,minute-of-hour,hour-of-day - Plus
default— let the system pick based on the field's base type.