@gooddata/sdk-maql-language-server 0.0.0-stage → 11.65.0-alpha.10

package/esm/completions/sort.js

@@ -0,0 +1,88 @@
+// (C) 2022-2026 GoodData Corporation
+import { Kind } from "./descriptions.js";
+const defaultPrefix = "90__";
+const sortPrefixes = {
+    [Kind.LabelElement]: "00__",
+    [Kind.Attribute]: "20__",
+    //    [Kind.Label]: "20__", // this is the same as Kind.Label is the same as Kind.Attribute
+    [Kind.Dataset]: "21__",
+    [Kind.Fact]: "22__",
+    [Kind.Metric]: "25__",
+    [Kind.Granularity]: "30__",
+    [Kind.Function]: "40__",
+    [Kind.Keyword]: "41__",
+    [Kind.Boolean]: "42__",
+    [Kind.Operator]: "99__",
+};
+function getFunctionSortTemplate(functionName, prefixes) {
+    // Handle IFNULL function
+    if (functionName === "IFNULL") {
+        return prefixes([Kind.Metric, Kind.Function]);
+    }
+    // Handle statistical functions
+    const statisticalFunctions = [
+        "CORREL",
+        "COVAR",
+        "COVARP",
+        "FORECAST",
+        "RSQ",
+        "STDEV",
+        "STDEVP",
+        "VAR",
+        "VARP",
+    ];
+    if (statisticalFunctions.includes(functionName)) {
+        return prefixes([Kind.Fact, Kind.Metric]);
+    }
+    // Default case for other functions
+    return prefixes([Kind.Granularity, Kind.Label, Kind.Fact, Kind.Metric, Kind.Function]);
+}
+export function adjustSortText(list, context) {
+    let template = Object.assign({}, sortPrefixes);
+    const prefixes = (order) => order.reduce((prev, curr, idx) => ({
+        ...prev,
+        [curr]: `${String(idx + 1).padStart(2, "0")}__`,
+    }), template);
+    // Find the lowest non-empty (therefore complete and valid) AST node if such exists
+    const lowestNode = context.nodeStack.find((node) => node.type !== "");
+    switch (lowestNode?.type) {
+        case "metric":
+            template = prefixes([Kind.Function, Kind.Metric, Kind.Fact]);
+            break;
+        case "and":
+        case "or":
+        case "not":
+            template = prefixes([Kind.Label, Kind.Metric, Kind.Fact]);
+            break;
+        case "case":
+        case "when":
+            template = prefixes([Kind.Metric, Kind.Fact, Kind.Label, Kind.Function]);
+            break;
+        case "where":
+        case "having":
+            template = prefixes([Kind.Label, Kind.Metric, Kind.Fact, Kind.Function]);
+            break;
+        case "by":
+            template = prefixes([Kind.Dataset, Kind.Label, Kind.Keyword]);
+            break;
+        case "+":
+        case "=":
+        case "/":
+        case "*":
+            template = prefixes([Kind.Fact, Kind.Metric]);
+            break;
+        case "function":
+        case "time macro":
+            template = getFunctionSortTemplate(lowestNode.name, prefixes);
+            break;
+    }
+    list.items = list.items.map((it) => {
+        const prefix = it.kind ? (template[it.kind] ?? defaultPrefix) : defaultPrefix;
+        return {
+            ...it,
+            sortText: prefix + (it.sortText ?? it.label),
+            preselect: true, // a hack to force the client to use sortText
+        };
+    });
+    return list;
+}

package/esm/constants.d.ts

@@ -0,0 +1,21 @@
+export declare const LanguageId: string;
+export declare const diagnosticsSource: string;
+export declare enum ErrorCodes {
+    InputMismatch = 0,
+    NoViableAlternative = 1,
+    FailedPredicate = 2,
+    UnspecifiedError = 3,
+    UnrecognizedInput = 4,
+    UnterminatedString = 5,
+    UndefinedKeyword = 6,
+    InvalidType = 7,
+    ExtraIdentifiersInObject = 8,
+    ObjectNotFound = 9,
+    LabelElementNotFound = 10,
+    InvalidOperator = 11,
+    SuspiciousStringLiteral = 12,
+    ParameterValueNotAllowed = 13,
+    ParameterValueUncovered = 14,
+    InvalidLabelElementValue = 15
+}
+//# sourceMappingURL=constants.d.ts.map

package/esm/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,EAAE,MAAe,CAAC;AAEzC,eAAO,MAAM,iBAAiB,QAA2B,CAAC;AAE1D,oBAAY,UAAU;IAClB,aAAa,IAAI;IACjB,mBAAmB,IAAI;IACvB,eAAe,IAAI;IACnB,gBAAgB,IAAI;IACpB,iBAAiB,IAAI;IACrB,kBAAkB,IAAI;IACtB,gBAAgB,IAAI;IACpB,WAAW,IAAI;IACf,wBAAwB,IAAI;IAC5B,cAAc,IAAI;IAClB,oBAAoB,KAAK;IACzB,eAAe,KAAK;IACpB,uBAAuB,KAAK;IAC5B,wBAAwB,KAAK;IAC7B,uBAAuB,KAAK;IAC5B,wBAAwB,KAAK;CAChC"}

package/esm/constants.js

@@ -0,0 +1,22 @@
+// (C) 2021-2026 GoodData Corporation
+export const LanguageId = "maql";
+export const diagnosticsSource = LanguageId.toUpperCase();
+export var ErrorCodes;
+(function (ErrorCodes) {
+    ErrorCodes[ErrorCodes["InputMismatch"] = 0] = "InputMismatch";
+    ErrorCodes[ErrorCodes["NoViableAlternative"] = 1] = "NoViableAlternative";
+    ErrorCodes[ErrorCodes["FailedPredicate"] = 2] = "FailedPredicate";
+    ErrorCodes[ErrorCodes["UnspecifiedError"] = 3] = "UnspecifiedError";
+    ErrorCodes[ErrorCodes["UnrecognizedInput"] = 4] = "UnrecognizedInput";
+    ErrorCodes[ErrorCodes["UnterminatedString"] = 5] = "UnterminatedString";
+    ErrorCodes[ErrorCodes["UndefinedKeyword"] = 6] = "UndefinedKeyword";
+    ErrorCodes[ErrorCodes["InvalidType"] = 7] = "InvalidType";
+    ErrorCodes[ErrorCodes["ExtraIdentifiersInObject"] = 8] = "ExtraIdentifiersInObject";
+    ErrorCodes[ErrorCodes["ObjectNotFound"] = 9] = "ObjectNotFound";
+    ErrorCodes[ErrorCodes["LabelElementNotFound"] = 10] = "LabelElementNotFound";
+    ErrorCodes[ErrorCodes["InvalidOperator"] = 11] = "InvalidOperator";
+    ErrorCodes[ErrorCodes["SuspiciousStringLiteral"] = 12] = "SuspiciousStringLiteral";
+    ErrorCodes[ErrorCodes["ParameterValueNotAllowed"] = 13] = "ParameterValueNotAllowed";
+    ErrorCodes[ErrorCodes["ParameterValueUncovered"] = 14] = "ParameterValueUncovered";
+    ErrorCodes[ErrorCodes["InvalidLabelElementValue"] = 15] = "InvalidLabelElementValue";
+})(ErrorCodes || (ErrorCodes = {}));

package/esm/dateElementFormat.d.ts

@@ -0,0 +1,9 @@
+import { type DateAttributeGranularity } from "@gooddata/sdk-model";
+/**
+ * Checks that the value of a date attribute element has the format the backend expects for the granularity.
+ *
+ * @returns the expected pattern when the value does not match it, undefined when the value is valid
+ *  or the granularity is not checked
+ */
+export declare function getInvalidDateElementPattern(value: string, granularity: DateAttributeGranularity | undefined): string | undefined;
+//# sourceMappingURL=dateElementFormat.d.ts.map

package/esm/dateElementFormat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateElementFormat.d.ts","sourceRoot":"","sources":["../src/dateElementFormat.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAuDpE;;;;;GAKG;AACH,wBAAgB,4BAA4B,CACxC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,wBAAwB,GAAG,SAAS,GAClD,MAAM,GAAG,SAAS,CAMpB"}

package/esm/dateElementFormat.js

@@ -0,0 +1,60 @@
+// (C) 2026 GoodData Corporation
+/**
+ * Value patterns the backend expects for date attribute elements used in MAQL, per granularity.
+ *
+ * Mirrors the backend (gdc-nas) implementation, which is the source of truth:
+ * - patterns: `libraries/calq/calcique-lib/src/main/kotlin/generator/model/date/GregorianChronological.kt`
+ *   and `FiscalChronological.kt` (`pattern` of each granularity object)
+ * - regex derivation: `Chronological.valueRegex` in `.../generator/model/date/Chronological.kt`
+ * - check: `TypeHandler.checkDateFormat` in `libraries/calq/calcique-lib/src/main/kotlin/interpreter/TypeHandler.kt`
+ *
+ * The backend regex is deliberately loose (e.g. month `[01]?\d` accepts "13"), and this check must accept
+ * exactly the same values, otherwise the editor would reject expressions the backend accepts.
+ * Any change on the backend side has to be aligned here manually.
+ *
+ * Periodical granularities (day of week, month of year, ...) are validated by the backend as integer ranges
+ * that partly depend on the workspace configuration; they are not checked here and rely on the backend
+ * error returned by the elements query instead.
+ */
+const granularityPatterns = {
+    "GDC.time.second": "YYYY-MM-DD HH24:MI:SS",
+    "GDC.time.minute": "YYYY-MM-DD HH24:MI",
+    "GDC.time.hour": "YYYY-MM-DD HH24",
+    "GDC.time.date": "YYYY-MM-DD",
+    "GDC.time.week_us": "IYYY-IW",
+    "GDC.time.month": "YYYY-MM",
+    "GDC.time.quarter": "YYYY-Q",
+    "GDC.time.year": "YYYY",
+    "GDC.time.fiscal_month": "YYYY-MM",
+    "GDC.time.fiscal_quarter": "YYYY-Q",
+    "GDC.time.fiscal_year": "YYYY",
+};
+// Same replacement order as Chronological.valueRegex on the backend
+const patternTokens = [
+    ["YYYY", "(\\d{1,4})"],
+    ["IYYY", "(\\d{1,4})"],
+    ["Q", "([1-4])"],
+    ["MM", "([01]?\\d)"],
+    ["IW", "([0-5]?\\d)"],
+    ["DD", "([0-3]?\\d)"],
+    ["HH24", "([0-2]?\\d)"],
+    ["MI", "([0-5]?\\d)"],
+    ["SS", "([0-5]?\\d)"],
+];
+const granularityRegexes = new Map(Object.entries(granularityPatterns).map(([granularity, pattern]) => [
+    granularity,
+    new RegExp(`^${patternTokens.reduce((regex, [token, replacement]) => regex.replaceAll(token, replacement), pattern)}$`),
+]));
+/**
+ * Checks that the value of a date attribute element has the format the backend expects for the granularity.
+ *
+ * @returns the expected pattern when the value does not match it, undefined when the value is valid
+ *  or the granularity is not checked
+ */
+export function getInvalidDateElementPattern(value, granularity) {
+    if (!granularity || value === "") {
+        return undefined; // the backend considers an empty string to be NULL for dates
+    }
+    const regex = granularityRegexes.get(granularity);
+    return regex && !regex.test(value) ? granularityPatterns[granularity] : undefined;
+}

package/esm/decorations.d.ts

@@ -0,0 +1,46 @@
+import { type MarkupContent, type Range } from "vscode-languageserver";
+import { type ITigerMetadataObject, type LdmObjects } from "./metadata/model.js";
+/**
+ * The decorations as defined in this file are heavily inspired by Monaco editor decorations.
+ */
+/**
+ * A decoration in the model.
+ *
+ * @internal
+ */
+export interface IDecoration {
+    /**
+     * Range that this decoration covers.
+     */
+    range: Range;
+    /**
+     * Options associated with this decoration.
+     */
+    options: IDecorationOptions;
+}
+/**
+ * Options for a decoration.
+ *
+ * @internal
+ */
+export interface IDecorationOptions {
+    /**
+     * Array of MarkdownString to render as the decoration message.
+     */
+    hoverMessage?: MarkupContent | MarkupContent[];
+    /**
+     * If set, text will be injected in the view after the range.
+     */
+    label: string;
+    /**
+     * Type of current decorator
+     */
+    type: DecorationType;
+}
+/**
+ * @internal
+ */
+export type DecorationType = ITigerMetadataObject["tigerType"] | "dateAttribute" | "dateLabel";
+export declare function decorate(query: string, ldmObjects?: LdmObjects): IDecoration[];
+export declare function createDecoration(range: Range, label: string, type: DecorationType): IDecoration;
+//# sourceMappingURL=decorations.d.ts.map

package/esm/decorations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorations.d.ts","sourceRoot":"","sources":["../src/decorations.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAGvE,OAAO,EACH,KAAK,oBAAoB,EACzB,KAAK,UAAU,EAGlB,MAAM,qBAAqB,CAAC;AAI7B;;GAEG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IACb;;OAEG;IACH,OAAO,EAAE,kBAAkB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;OAEG;IACH,YAAY,CAAC,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;IAC/C;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,EAAE,cAAc,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC,WAAW,CAAC,GAAG,eAAe,GAAG,WAAW,CAAC;AAE/F,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,WAAW,EAAE,CAI9E;AA6BD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,WAAW,CAQ/F"}

package/esm/decorations.js

@@ -0,0 +1,42 @@
+// (C) 2021-2026 GoodData Corporation
+import { findAllObjects } from "./findObjects.js";
+import { isITigerAttribute, isITigerLabel, } from "./metadata/model.js";
+import { MaqlMetric } from "./parseMaql.js";
+export function decorate(query, ldmObjects) {
+    const metric = new MaqlMetric(query);
+    // decorate objects with business names
+    return ldmObjects ? decorateBusinessNames(metric, ldmObjects) : [];
+}
+function decorateBusinessNames(metric, ldmObjects) {
+    const foundObjects = findAllObjects(metric);
+    return foundObjects
+        .map((objectAndRange) => {
+        const fullObject = ldmObjects.findObject(objectAndRange);
+        if (!fullObject)
+            return null;
+        return {
+            range: objectAndRange.range.toRange(),
+            ...fullObject,
+        };
+    })
+        .filter((foundObject) => !!foundObject)
+        .map((foundObject) => createDecoration(foundObject.range, foundObject.title, toDecorationType(foundObject)));
+}
+function toDecorationType(object) {
+    if (isITigerAttribute(object)) {
+        return object.tigerTypeModifier === "date" ? "dateAttribute" : object.tigerType;
+    }
+    if (isITigerLabel(object)) {
+        return object.tigerTypeModifier === "date" ? "dateLabel" : object.tigerType;
+    }
+    return object.tigerType;
+}
+export function createDecoration(range, label, type) {
+    return {
+        range,
+        options: {
+            label,
+            type,
+        },
+    };
+}

package/esm/diagnostics.d.ts

@@ -0,0 +1,12 @@
+import { Diagnostic } from "vscode-languageserver";
+import { ErrorCodes } from "./constants.js";
+import { type LabelElementsFunc, type LdmObjects } from "./metadata/model.js";
+interface IErrorDescription {
+    message(tokenText?: string): string;
+    code: ErrorCodes;
+}
+export declare const errorTokenDescriptions: Map<number, IErrorDescription>;
+export declare const errorTokens: number[];
+export declare function validate(query: string, ldmObjects?: LdmObjects, labelElementsFunc?: LabelElementsFunc): Promise<Diagnostic[]>;
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/esm/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAA6B,MAAM,uBAAuB,CAAC;AAc9E,OAAO,EAAE,UAAU,EAAqB,MAAM,gBAAgB,CAAC;AAI/D,OAAO,EAEH,KAAK,iBAAiB,EACtB,KAAK,UAAU,EAGlB,MAAM,qBAAqB,CAAC;AAO7B,UAAU,iBAAiB;IACvB,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEpC,IAAI,EAAE,UAAU,CAAC;CACpB;AAED,eAAO,MAAM,sBAAsB,gCAgDjC,CAAC;AAEH,eAAO,MAAM,WAAW,EAAE,MAAM,EAA8C,CAAC;AAE/E,wBAAsB,QAAQ,CAC1B,KAAK,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,UAAU,EACvB,iBAAiB,CAAC,EAAE,iBAAiB,GACtC,OAAO,CAAC,UAAU,EAAE,CAAC,CAsBvB"}

package/esm/diagnostics.js

@@ -0,0 +1,259 @@
+// (C) 2021-2026 GoodData Corporation
+import { DefaultErrorStrategy, FailedPredicateException, InputMismatchException, NoViableAltException, } from "antlr4ng";
+import { groupBy } from "lodash-es";
+import { Diagnostic, DiagnosticSeverity, Range } from "vscode-languageserver";
+import { AbstractAstVisitor, MaqlLexer, SyntaxErrorListener, } from "@gooddata/maql-antlr4ts";
+import { isUnexpectedResponseError } from "@gooddata/sdk-backend-spi";
+import { areObjRefsEqual, serializeObjRef } from "@gooddata/sdk-model";
+import { ErrorCodes, diagnosticsSource } from "./constants.js";
+import { getInvalidDateElementPattern } from "./dateElementFormat.js";
+import { findAllObjects } from "./findObjects.js";
+import { labelElementsFinder } from "./labelElements.js";
+import { isITigerAttribute, isITigerLabel, } from "./metadata/model.js";
+import { validateParameterConstraints } from "./parameterConstraints.js";
+import { MaqlMetric } from "./parseMaql.js";
+import { AntlrRange, defaultRange, tokenRange } from "./tokenRanges.js";
+import { AstTypeChecker } from "./types/typeChecking.js";
+import { TypeModel } from "./types/typeModel.js";
+export const errorTokenDescriptions = new Map([
+    [
+        MaqlLexer.UnterminatedString,
+        {
+            message() {
+                return "missing '\"' at the end of a string";
+            },
+            code: ErrorCodes.UnterminatedString,
+        },
+    ],
+    // [
+    //     // TODO Reuse for "no function definition found"
+    //     MaqlLexer.Identifier,
+    //     {
+    //         message(tokenText: string): string {
+    //             return `undefined keyword '${tokenText}'`;
+    //         },
+    //         code: ErrorCodes.UndefinedKeyword,
+    //     },
+    // ],
+    [
+        MaqlLexer.ERROR_CHARACTER,
+        {
+            message(tokenText) {
+                return `unexpected character '${tokenText}'`;
+            },
+            code: ErrorCodes.UnrecognizedInput,
+        },
+    ],
+    [
+        MaqlLexer.UNKNOWN_TYPE,
+        {
+            message(tokenText) {
+                return `invalid object type '${tokenText}'`;
+            },
+            code: ErrorCodes.InvalidType,
+        },
+    ],
+    // [
+    //     // was removed with top-win identifiers, will probably be reintroduced at some point in the future
+    //     MaqlLexer.OBJECT_EXTRA_SUFFIX,
+    //     {
+    //         message(tokenText: string): string {
+    //             return `too many identifiers: ${tokenText.slice(1).replace(/\//g, ", ")}`;
+    //         },
+    //         code: ErrorCodes.ExtraIdentifiersInObject,
+    //     },
+    // ],
+]);
+export const errorTokens = Array.from(errorTokenDescriptions.keys());
+export async function validate(query, ldmObjects, labelElementsFunc) {
+    const metric = new MaqlMetric(query);
+    const parserDiagnostics = validateByParser(metric);
+    // If any errors were encountered, go through all tokens and match any error tokens to specific diagnostics
+    const lexerDiagnostics = parserDiagnostics.length > 0 ? validateByLexer(metric) : [];
+    // Verify that semantic rules are followed
+    const semanticDiagnostics = validateSemantics(metric.ast);
+    // Verify that objects in the query exist
+    const objectsDiagnostics = ldmObjects ? validateObjects(metric, ldmObjects) : [];
+    // Verify that strings in the query are valid label elements
+    const labelDiagnostics = await validateLabelElements(metric, ldmObjects, labelElementsFunc);
+    // Verify types
+    const typeDiagnostics = ldmObjects ? validateTypes(metric.ast, ldmObjects) : [];
+    const constraintsDiagnostics = ldmObjects ? validateParameterConstraints(metric, ldmObjects) : [];
+    return parserDiagnostics.concat(lexerDiagnostics, semanticDiagnostics, typeDiagnostics, objectsDiagnostics, constraintsDiagnostics, labelDiagnostics.flat());
+}
+function validateSemantics(root) {
+    const validator = new SemanticValidator();
+    return validator.visit(root);
+}
+function validateByParser(metric) {
+    const syntaxErrorListener = new SyntaxErrorListener();
+    // oxlint-disable-next-line @typescript-eslint/no-unused-expressions
+    metric.addErrorListener(syntaxErrorListener).setErrorHandler(new DefaultErrorStrategy()).tree; // parse MAQL
+    return syntaxErrorListener.antlrErrors.map((error) => {
+        const errorCode = ((parserError) => {
+            // only the actual instance of error will match 'true'
+            switch (true) {
+                case parserError instanceof InputMismatchException:
+                    return ErrorCodes.InputMismatch;
+                case parserError instanceof NoViableAltException:
+                    return ErrorCodes.NoViableAlternative;
+                case parserError instanceof FailedPredicateException:
+                    return ErrorCodes.FailedPredicate;
+                default:
+                    return ErrorCodes.UnspecifiedError;
+            }
+        })(error.error);
+        const range = error.offendingToken
+            ? tokenRange(error.offendingToken)
+            : defaultRange(error.position.line, error.position.character);
+        return Diagnostic.create(range, error.message, DiagnosticSeverity.Error, errorCode, diagnosticsSource);
+    });
+}
+function validateByLexer(metric) {
+    return metric.lexer
+        .getAllTokens()
+        .map((token) => handleErrorToken(token))
+        .filter((diagnostic) => !!diagnostic);
+}
+function validateObjects(metric, ldmObjects) {
+    const foundObjects = findAllObjects(metric);
+    return foundObjects
+        .map((foundObject) => {
+        const existingObjects = foundObject.tigerType ? ldmObjects.get(foundObject.tigerType) : undefined;
+        if (!existingObjects) {
+            return Diagnostic.create(foundObject.range.toRange(), `type '${foundObject.actualType}' is not valid`, DiagnosticSeverity.Error, ErrorCodes.InvalidType, diagnosticsSource);
+        }
+        return existingObjects.find((obj) => areObjRefsEqual(obj.ref, foundObject.ref))
+            ? null
+            : Diagnostic.create(foundObject.range.toRange(), `${foundObject.tigerType} '${foundObject.id}' not found`, DiagnosticSeverity.Error, ErrorCodes.ObjectNotFound, diagnosticsSource);
+    })
+        .filter((diagnostic) => !!diagnostic);
+}
+async function validateLabelElements(metric, ldmObjects, labelElementsFunc) {
+    if (!ldmObjects && !labelElementsFunc) {
+        return [];
+    }
+    const foundPairs = labelElementsFinder(metric);
+    const stringsGrouped = groupBy(foundPairs, (pair) => serializeObjRef(pair[0].ref));
+    return Promise.all(Object.entries(stringsGrouped).map(async ([_ref, pairs]) => {
+        const label = pairs[0][0]; // all the labels from 'pairs' have the same ref (identity)
+        const granularity = getDateGranularity(label, ldmObjects);
+        const formatDiagnostics = [];
+        const elements = [];
+        pairs.forEach(([, element]) => {
+            const expectedPattern = getInvalidDateElementPattern(element.string, granularity);
+            if (expectedPattern) {
+                formatDiagnostics.push(invalidLabelElementDiagnostic(element, `"${element.string}" does not match the format ${expectedPattern} expected by {${label.tigerType}/${label.id}}`));
+            }
+            else {
+                elements.push(element);
+            }
+        });
+        if (!labelElementsFunc || elements.length === 0) {
+            return formatDiagnostics; // malformed values are not sent to the backend, it would reject them anyway
+        }
+        const result = await labelElementsFunc([label], [], { elements: { values: elements.map((element) => element.string) } }, elements.length);
+        if (result.rejected.includes(label)) {
+            // the query for the label was rejected, only a rejection of the values themselves allows a claim
+            return formatDiagnostics.concat(rejectedElementsDiagnostics(elements, result.rejectionReasons?.get(label)));
+        }
+        if (result.list.elements.length === elements.length) {
+            return formatDiagnostics; // all label elements were returned
+        }
+        const resultElements = result.list.elements.map((element) => element.title);
+        return formatDiagnostics.concat(elements
+            .map((element) => labelElementInResult(element, label, resultElements))
+            .filter((diagnostic) => !!diagnostic));
+    }));
+}
+function getDateGranularity(label, ldmObjects) {
+    const object = ldmObjects?.findObject(label);
+    return object &&
+        (isITigerLabel(object) || isITigerAttribute(object)) &&
+        object.tigerTypeModifier === "date"
+        ? object.granularity
+        : undefined;
+}
+/**
+ * The backend rejects the elements query with 400 Bad Request when the values are invalid for the label,
+ * e.g. a date value in a wrong format for a granularity the client-side check does not cover.
+ * Any other failure (network, server error, ...) allows no claim about the values.
+ */
+function rejectedElementsDiagnostics(elements, reason) {
+    if (!isUnexpectedResponseError(reason) || reason.httpStatus !== 400) {
+        return [];
+    }
+    const responseBody = reason.responseBody;
+    const detail = typeof responseBody === "object" &&
+        responseBody !== null &&
+        "detail" in responseBody &&
+        typeof responseBody.detail === "string"
+        ? responseBody.detail
+        : undefined;
+    if (!detail) {
+        return [];
+    }
+    // the backend reports the first offending value, mark it if it can be identified, otherwise mark all of them
+    const offending = elements.filter((element) => detail.includes(`'${element.string}'`));
+    return (offending.length > 0 ? offending : elements).map((element) => invalidLabelElementDiagnostic(element, detail));
+}
+function invalidLabelElementDiagnostic(element, message) {
+    return Diagnostic.create(element.range.toRange(), message, DiagnosticSeverity.Error, ErrorCodes.InvalidLabelElementValue, diagnosticsSource);
+}
+function validateTypes(ast, ldmObjects) {
+    const stringLabelIds = ldmObjects.get("label", "regular").map((label) => label.id);
+    const dateLabelIds = ldmObjects.get("label", "date").map((label) => label.id);
+    const typeChecker = new AstTypeChecker(new TypeModel(stringLabelIds, dateLabelIds));
+    typeChecker.visit(ast);
+    const typeViolations = typeChecker.typeConstraintsViolations;
+    return typeViolations.map((violation) => {
+        const range = violation.range
+            ? AntlrRange.fromAstRange(violation.range).toRange()
+            : Range.create(0, 0, 0, 0);
+        return Diagnostic.create(range, violation.message, DiagnosticSeverity.Error, ErrorCodes.InvalidType, diagnosticsSource);
+    });
+}
+/**
+ * @returns null if "element" is in "resultElements", diagnostic signifying the error otherwise
+ */
+function labelElementInResult(element, label, resultElements) {
+    return resultElements.includes(element.string)
+        ? null
+        : Diagnostic.create(element.range.toRange(), `"${element.string}" is not an element of {${label.tigerType}/${label.id}}`, DiagnosticSeverity.Warning, ErrorCodes.LabelElementNotFound, diagnosticsSource);
+}
+class SemanticValidator extends AbstractAstVisitor {
+    EQUALITY_OPERATORS = ["=", "<>", "in", "not in"];
+    defaultResult() {
+        return [];
+    }
+    aggregateResult(aggregate, nextResult) {
+        return aggregate.concat(nextResult);
+    }
+    visitOperatorNode(node) {
+        const childrenResult = this.visitChildren(node);
+        if (!this.EQUALITY_OPERATORS.includes(node.type) &&
+            node.range !== undefined &&
+            // this is only a shallow check, consider expanding the type system for a full check
+            node.content.some((operand) => operand.type === "null")) {
+            return this.aggregateResult(childrenResult, [
+                Diagnostic.create(AntlrRange.fromAstRange(node.range).toRange(), "Only equality operators can be used with NULL", DiagnosticSeverity.Error, ErrorCodes.InvalidOperator),
+            ]);
+        }
+        return childrenResult;
+    }
+    visitStringLiteralNode(node) {
+        if (node.value.toLowerCase() === "null" && node.range) {
+            return [
+                Diagnostic.create(AntlrRange.fromAstRange(node.range).toRange(), `This is a string literal containing the word "${node.value}". ` +
+                    "Perhaps you meant the NULL keyword (no quotes)?", DiagnosticSeverity.Warning, ErrorCodes.SuspiciousStringLiteral),
+            ];
+        }
+        return [];
+    }
+}
+function handleErrorToken(token) {
+    const errorDescription = errorTokenDescriptions.get(token.type);
+    if (!errorDescription)
+        return;
+    return Diagnostic.create(tokenRange(token), errorDescription.message(token.text), DiagnosticSeverity.Error, errorDescription.code, diagnosticsSource);
+}

package/esm/docs/en/docs/create-metrics/maql/aggregation/approximate_count.d.ts

@@ -0,0 +1,2 @@
+export declare const content = "# APPROXIMATE_COUNT\nUse APPROXIMATE_COUNT to return the approximate number of unique values for an attribute. Because the returned value is a statistical estimate and not an exact figure, this function can increase the processing speed when analyzing large datasets. You can use APPROXIMATE_COUNT anywhere you can use COUNT. The smaller the amount of data to process, the more likely that the returned results of APPROXIMATE_COUNT will match the results of COUNT. \n\n - APPROXIMATE_COUNT is available only for workspaces that use [Vertica](https://www.gooddata.com/developers/cloud-native/doc/hosted/connect-data/create-data-sources/vertica/) Data Sources.\n - APPROXIMATE_COUNT uses the Vertica default behavior for APPROXIMATE_COUNT_DISTINCT. It is not possible to use modifiers.\n - GoodData defaults to COUNT when APPROXIMATE_COUNT is unavailable in a workspace.\n\n## Syntax\n\nAPPROXIMATE_COUNT uses the following syntax:\n\n\n  |Form       |        Syntax            |                                           Example|\n  |------------------ |------------------------------------------------------------| --------------------------------------------|\n  |single parameter   |`SELECT APPROXIMATE_COUNT(attribute)`                                    |`SELECT APPROXIMATE_COUNT({attribute/order_id})`|\n  |two parameters     |`SELECT APPROXIMATE_COUNT(attribute, primary_key)`                       |`SELECT APPROXIMATE_COUNT({attribute/order_id}, {attribute/campaign_id})`|\n  |with USING         |`SELECT APPROXIMATE_COUNT(attribute) USING primary_key`   |`SELECT APPROXIMATE_COUNT({attribute/order_id}) USING {attribute/campaign_id}`|\n\n\n### Single-Parameter Version\n\nThe single-parameter version of APPROXIMATE_COUNT dynamically gets the context of\nwhere to count from the visualization it is used in.\n\n### Two-Parameter Version\n\nIn the two-parameter version, the context where to count the attribute\nis determined explicitly by the second parameter - the primary key of\nthe dataset.\n\nThe primary key is connection point between datasets. It connects the\nAPPROXIMATE_COUNT function's first parameter to the dataset in which the count is\nto take place.\n\n### Specifying APPROXIMATE_COUNT Context Resolution with USING\n\nIn a metric, USING provides a hint for which context should be used.\nThe context for the computation of APPROXIMATE COUNT may be ambiguous if there are\nmultiple fact datasets in your logical data model that relate to a counted attribute. \n\nThe following image shows a model with the fact datasets `Purchases` and `Sales` and\nhas both datasets connected to the `Store ID` and `Product ID` attributes.\n\n![model for count example](https://www.gooddata.com/developers/cloud-native/doc/maql/count-ldm-using.png)\n\nTo create a metric that resolves with a specific context, you can specify USING in your metric like in the following \nexample: `SELECT COUNT({label/inventory.productid}) USING {label/purchases.purchaseid}`. \n\nWith this example, the visualization will show the approximate number of uniquely purchased products per store \nbecause the attribute `Purchase ID` from the `Purchases` dataset is in the USING clause.\n\nWith the example model, if you build a visualization to display the approximate count of products per store with \n`SELECT COUNT({label/inventory.productid})` and slice it by Store without specifying USING, it is ambiguous whether \nthe visualization is displaying the approximate number of unique products that have been purchased by store or the\napproximate number of unique products that have been sold by the store.\n\nThe attribute in the USING clause can be any attribute which uniquely determines the correct context. For example, you\ncan also use an attribute from the `Purchase Date` dataset in the USING clause. This uses the `Purchases` dataset as \nthe context because the `Sales` dataset has no relationships to `Purchase Date`: \n`SELECT COUNT({label/inventory.productid}) USING {label/purchasedate.year}`";
+//# sourceMappingURL=approximate_count.d.ts.map

package/esm/docs/en/docs/create-metrics/maql/aggregation/approximate_count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approximate_count.d.ts","sourceRoot":"","sources":["../../../../../../../src/docs/en/docs/create-metrics/maql/aggregation/approximate_count.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,OAAO,u6HA2D0D,CAAC"}

package/esm/docs/en/docs/create-metrics/maql/aggregation/approximate_count.js

@@ -0,0 +1,61 @@
+// (C) 2021-2026 GoodData Corporation
+export const content = `# APPROXIMATE_COUNT
+Use APPROXIMATE_COUNT to return the approximate number of unique values for an attribute. Because the returned value is a statistical estimate and not an exact figure, this function can increase the processing speed when analyzing large datasets. You can use APPROXIMATE_COUNT anywhere you can use COUNT. The smaller the amount of data to process, the more likely that the returned results of APPROXIMATE_COUNT will match the results of COUNT. 
+
+ - APPROXIMATE_COUNT is available only for workspaces that use [Vertica](https://www.gooddata.com/developers/cloud-native/doc/hosted/connect-data/create-data-sources/vertica/) Data Sources.
+ - APPROXIMATE_COUNT uses the Vertica default behavior for APPROXIMATE_COUNT_DISTINCT. It is not possible to use modifiers.
+ - GoodData defaults to COUNT when APPROXIMATE_COUNT is unavailable in a workspace.
+
+## Syntax
+
+APPROXIMATE_COUNT uses the following syntax:
+
+
+  |Form       |        Syntax            |                                           Example|
+  |------------------ |------------------------------------------------------------| --------------------------------------------|
+  |single parameter   |\`SELECT APPROXIMATE_COUNT(attribute)\`                                    |\`SELECT APPROXIMATE_COUNT({attribute/order_id})\`|
+  |two parameters     |\`SELECT APPROXIMATE_COUNT(attribute, primary_key)\`                       |\`SELECT APPROXIMATE_COUNT({attribute/order_id}, {attribute/campaign_id})\`|
+  |with USING         |\`SELECT APPROXIMATE_COUNT(attribute) USING primary_key\`   |\`SELECT APPROXIMATE_COUNT({attribute/order_id}) USING {attribute/campaign_id}\`|
+
+
+### Single-Parameter Version
+
+The single-parameter version of APPROXIMATE_COUNT dynamically gets the context of
+where to count from the visualization it is used in.
+
+### Two-Parameter Version
+
+In the two-parameter version, the context where to count the attribute
+is determined explicitly by the second parameter - the primary key of
+the dataset.
+
+The primary key is connection point between datasets. It connects the
+APPROXIMATE_COUNT function's first parameter to the dataset in which the count is
+to take place.
+
+### Specifying APPROXIMATE_COUNT Context Resolution with USING
+
+In a metric, USING provides a hint for which context should be used.
+The context for the computation of APPROXIMATE COUNT may be ambiguous if there are
+multiple fact datasets in your logical data model that relate to a counted attribute. 
+
+The following image shows a model with the fact datasets \`Purchases\` and \`Sales\` and
+has both datasets connected to the \`Store ID\` and \`Product ID\` attributes.
+
+![model for count example](https://www.gooddata.com/developers/cloud-native/doc/maql/count-ldm-using.png)
+
+To create a metric that resolves with a specific context, you can specify USING in your metric like in the following 
+example: \`SELECT COUNT({label/inventory.productid}) USING {label/purchases.purchaseid}\`. 
+
+With this example, the visualization will show the approximate number of uniquely purchased products per store 
+because the attribute \`Purchase ID\` from the \`Purchases\` dataset is in the USING clause.
+
+With the example model, if you build a visualization to display the approximate count of products per store with 
+\`SELECT COUNT({label/inventory.productid})\` and slice it by Store without specifying USING, it is ambiguous whether 
+the visualization is displaying the approximate number of unique products that have been purchased by store or the
+approximate number of unique products that have been sold by the store.
+
+The attribute in the USING clause can be any attribute which uniquely determines the correct context. For example, you
+can also use an attribute from the \`Purchase Date\` dataset in the USING clause. This uses the \`Purchases\` dataset as 
+the context because the \`Sales\` dataset has no relationships to \`Purchase Date\`: 
+\`SELECT COUNT({label/inventory.productid}) USING {label/purchasedate.year}\``;