https://docs.holistics.io/assets/js/bb2574e4.8bd58452.js

1"use strict";(self.webpackChunkholistics_docs=self.webpackChunkholistics_docs||[]).push([["19259"],{38754(e,i,n){n.r(i),n.d(i,{metadata:()=>s,default:()=>h,frontMatter:()=>r,contentTitle:()=>l,toc:()=>c,assets:()=>o});var s=JSON.parse('{"id":"as-code/aml/overview","title":"AML Overview","description":"Analytical Modeling Language (AML) is used to describe data semantic model and business metrics within Holistics.","source":"@site/docs/as-code/aml/overview.md","sourceDirName":"as-code/aml","slug":"/as-code/aml/","permalink":"/as-code/aml/","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"title":"AML Overview","slug":"/as-code/aml/","description":"Analytical Modeling Language (AML) is used to describe data semantic model and business metrics within Holistics."},"sidebar":"docs","previous":{"title":"Databricks Metric Views","permalink":"/docs/connect/databases/databricks-metric-views"},"next":{"title":"AML vs YAML","permalink":"/as-code/amql/aml-vs-yaml"}}'),a=n(74848),t=n(28453);let r={title:"AML Overview",slug:"/as-code/aml/",description:"Analytical Modeling Language (AML) is used to describe data semantic model and business metrics within Holistics."},l,o={},c=[{value:"Introduction",id:"introduction",level:2},{value:"Why AML",id:"why-aml",level:2},{value:"Static types as a feedback loop for AI",id:"static-types-as-a-feedback-loop-for-ai",level:3},{value:"Design principles",id:"design-principles",level:2},{value:"Using AML in Holistics",id:"using-aml-in-holistics",level:2},{value:"Use cases highlights",id:"use-cases-highlights",level:2},{value:"Quick start",id:"quick-start",level:2}];function d(e){let i={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",strong:"strong",ul:"ul",...(0,t.R)(),...e.components};return(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(i.h2,{id:"introduction",children:"Introduction"}),"\n",(0,a.jsxs)(i.p,{children:[(0,a.jsx)(i.strong,{children:"AML (Analytical Modeling Language)"})," is a declarative language used to define data semantic models and other analytical objects in Holistics, like datasets and dashboards. It allows users to add more meaning to data without modifying the underlying structure, and make use of Holistics's powerful ",(0,a.jsx)(i.strong,{children:"Analytical Query Language (AQL)"})," to perform complex reports."]}),"\n",(0,a.jsx)(i.admonition,{title:"AML vs AQL",type:"note",children:(0,a.jsxs)(i.p,{children:[(0,a.jsx)(i.strong,{children:"AML"})," is how you ",(0,a.jsx)(i.em,{children:"model"})," your business \u2014 the structure, types, and reusable logic of your semantic layer. ",(0,a.jsx)(i.strong,{children:(0,a.jsx)(i.a,{href:"/as-code/aql/",children:"AQL"})})," is how you ",(0,a.jsx)(i.em,{children:"query"})," that model \u2014 the expression language that turns it into composable metrics and reports. This page covers AML; see the ",(0,a.jsx)(i.a,{href:"/as-code/aql/",children:"AQL docs"})," for querying."]})}),"\n",(0,a.jsx)(i.h2,{id:"why-aml",children:"Why AML"}),"\n",(0,a.jsxs)(i.p,{children:["We strongly believe in the vision of ",(0,a.jsx)(i.strong,{children:"analytics as-code"})," as the future of BI and analytics. However, in our opinion, there is not an adequate existing analytics-as-code language."]}),"\n",(0,a.jsxs)(i.p,{children:["While imperative languages like Python and R are powerful for complex logic, they are often overkill for defining semantic models. We advocate for a ",(0,a.jsx)(i.strong,{children:"declarative language"})," that is more suitable for defining semantic models and analytical objects. Unfortunately, existing declarative languages such as XML, JSON, and YAML have their limitations, including excessive ",(0,a.jsx)(i.strong,{children:"verbosity, ambiguity, and a lack of type checking"}),". Although LookML is a strong candidate, it is proprietary and only compatible with Looker."]}),"\n",(0,a.jsxs)(i.p,{children:["AML treats your analytics logic as ",(0,a.jsx)(i.strong,{children:"code, not configuration"}),". Three properties make this concrete:"]}),"\n",(0,a.jsxs)(i.ul,{children:["\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"First-class, typed objects"})," \u2014 models, dimensions, measures, metrics, and datasets are real objects with defined types, not SQL strings embedded in YAML. You can reference, pass around, and compose them."]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Static type checking"})," \u2014 a built-in type system validates your model as you write it. Errors surface in the IDE at authoring time, not at query time in a broken dashboard."]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Reusable constructs"})," \u2014 ",(0,a.jsx)(i.a,{href:"/reference/aml/constant",children:"Constant"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/func",children:"Func"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/module",children:"Module"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/extend",children:"Extend"}),", and ",(0,a.jsx)(i.a,{href:"/reference/aml/partial",children:"Partial"})," let you factor out and compose logic instead of copy-pasting it."]}),"\n"]}),"\n",(0,a.jsxs)(i.p,{children:["Together these make a model ",(0,a.jsx)(i.strong,{children:"maintainable"}),": less code, no drift, and changes that propagate from a single definition. This is what we mean by a language that is both ",(0,a.jsx)(i.strong,{children:"programmable"})," and ",(0,a.jsx)(i.strong,{children:"maintainable"})," \u2014 designed from the ground up for reusability, extensive parameterization, and modularization, so data teams can scale their analytical logic effortlessly as needs evolve."]}),"\n",(0,a.jsx)(i.h3,{id:"static-types-as-a-feedback-loop-for-ai",children:"Static types as a feedback loop for AI"}),"\n",(0,a.jsx)(i.p,{children:"Because AML is statically typed, the compiler checks every edit against the model immediately, whether a person writes it or an AI agent generates it. When an agent produces an invali

1d reference or a type mismatch, the compiler flags it at once, rather than letting the error surface later as a wrong number on a dashboard. This tight author-to-check loop is what makes agentic development on the semantic layer safe to trust."}),"\n",(0,a.jsx)(i.h2,{id:"design-principles",children:"Design principles"}),"\n",(0,a.jsxs)(i.ul,{children:["\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Declarative"}),": AML is designed for data analysts to declaratively specify the data semantic models and logic, not how to build those imperatively."]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Friendly yet rigorous syntax"}),": AML syntax is crafted with data analysts in mind, drawing inspiration from familiar languages like JSON, YAML, and JavaScript. It strikes a balance between being strict and well-defined, which promotes clarity and minimizes ambiguity in data and configuration expressions."]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Static type checking"}),": AML features a robust built-in static type system that provides instant feedback, enhancing the developer experience with top-notch smart auto-completion and template suggestions directly within the IDE. Both humans and AI agents catch mistakes at authoring time."]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.strong,{children:"Composability and Reusability"}),": Every component of the language is designed for reuse and composition, utilizing features such as ",(0,a.jsx)(i.a,{href:"/reference/aml/constant",children:"Constant"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/func",children:"Function"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/module",children:"Module"}),", ",(0,a.jsx)(i.a,{href:"/reference/aml/extend",children:"Extend"})," \u2014 so analytics logic scales across a team without duplication or drift."]}),"\n"]}),"\n",(0,a.jsx)(i.h2,{id:"using-aml-in-holistics",children:"Using AML in Holistics"}),"\n",(0,a.jsxs)(i.p,{children:["AML are written in ",(0,a.jsx)(i.code,{children:".<object-type>.aml"})," files in the ",(0,a.jsx)(i.a,{href:"/docs/development/aml-studio#supported-files",children:"Development workspace"}),". Currently the following objects are defined using AML:"]}),"\n",(0,a.jsxs)(i.ul,{children:["\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.a,{href:"/reference/aml/model",children:"Model"}),": ",(0,a.jsx)(i.code,{children:"model_name.model.aml"})]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.a,{href:"/reference/aml/dataset",children:"Dataset"}),": ",(0,a.jsx)(i.code,{children:"dataset_name.dataset.aml"})]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.a,{href:"/reference/aml/relationship",children:"Relationships"}),": ",(0,a.jsx)(i.code,{children:"relationships.aml"})]}),"\n",(0,a.jsxs)(i.li,{children:[(0,a.jsx)(i.a,{href:"/reference/aml/dashboard",children:"Dashboard"}),": ",(0,a.jsx)(i.code,{children:"dashboard_name.page.aml"})]}),"\n"]}),"\n",(0,a.jsx)(i.p,{children:"When users create a new object in the Modeling layer, base AML codes are automatically generated for the object. Users can extend on these bases either via the GUI, or manually write AML definitions (like dimension and measure definition, or model relationships...) which will also be reflected visually."}),"\n",(0,a.jsx)(i.h2,{id:"use-cases-highlights",children:"Use cases highlights"}),"\n",(0,a.jsx)(i.p,{children:"Some common reporting use cases that can be solved easily with AML and AQL includes:"}),"\n",(0,a.jsxs)(i.ul,{children:["\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/as-code/aql/cookbook/aql-cohort-retention",children:"Cohort Retention"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/as-code/aql/cookbook/aql-cumulative-metrics",children:"Cumulative Metrics"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/as-code/aql/cookbook/aql-nested-aggregation",children:"Nested Aggregation"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/as-code/aql/cookbook/aql-period-comparison",children:"Period comparison"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/docs/modeling/modeling-patterns/role-playing-dimensions",children:"Role-playing dimension"})}),"\n",(0,a.jsx)(i.li,{children:"..."}),"\n"]}),"\n",(0,a.jsxs)(i.p,{children:["Please visit our ",(0,a.jsx)(i.a,{href:"/guides/",children:"Guides"})," for more examples of how to leverage AML and AQL to answer your business questions."]}

1),"\n",(0,a.jsx)(i.h2,{id:"quick-start",children:"Quick start"}),"\n",(0,a.jsx)(i.p,{children:"To quickly get used to AML, we suggest checking out the following pages:"}),"\n",(0,a.jsxs)(i.ul,{children:["\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/reference/aml/examples",children:"AML Examples"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/reference/aml/model",children:"AML Model"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/reference/aml/field",children:"AML Dimension & Measure"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/reference/aml/dataset",children:"AML Dataset"})}),"\n",(0,a.jsx)(i.li,{children:(0,a.jsx)(i.a,{href:"/reference/aml/dashboard",children:"AML Dashboard"})}),"\n"]}),"\n",(0,a.jsx)(i.p,{children:"More documents can be found in the sidebar."})]})}function h(e={}){let{wrapper:i}={...(0,t.R)(),...e.components};return i?(0,a.jsx)(i,{...e,children:(0,a.jsx)(d,{...e})}):d(e)}},28453(e,i,n){n.d(i,{R:()=>r,x:()=>l});var s=n(96540);let a={},t=s.createContext(a);function r(e){let i=s.useContext(t);return s.useMemo(function(){return"function"==typeof e?e(i):{...i,...e}},[i,e])}function l(e){let i;return i=e.disableParentContext?"function"==typeof e.components?e.components(a):e.components||a:r(e.components),s.createElement(t.Provider,{value:i},e.children)}}}]);