feat(gooddata-sdk): add HLL_TYPE org setting helpers

Add typed `set_hll_type` / `get_hll_type` methods on
`CatalogOrganizationService` for the new `hyperLogLogType` org setting
introduced by gdc-nas (`HLL_TYPE("hyperLogLogType",
SettingConfiguration.HyperLogLogType)`).

The setting controls which HLL function family calcique uses when
generating SQL over HLL synopses:

- `"Native"` (default) emits StarRocks-native `HLL_*` functions —
  works when the platform (or PIPE pipeline) builds synopses
  StarRocks-side.
- `"Presto"` emits Presto-compatible HLL functions, required when
  synopses arrive from an upstream Presto pipeline (the binary layout
  and hash family differ between the two). Requires the StarRocks
  deployment to carry the Presto HLL UDFs.

Surface:
- `HLLType` Literal alias (`"Native" | "Presto"`) re-exported from
  `gooddata_sdk` for consumer annotations.
- `HLL_TYPE_SETTING_ID` (`"hyperLogLogType"`) and
  `HLL_TYPE_SETTING_TYPE` (`"HLL_TYPE"`) constants for callers that
  prefer to drive the generic `CatalogOrganizationSetting.init(...)`
  path directly.
- `service.set_hll_type(value)` is idempotent — tries update first,
  falls back to create when the setting doesn't exist yet.
- `service.get_hll_type()` returns `HLLType | None`; defensively
  returns `None` for unrecognized stored values.

Tests: 7 unit tests with mocked `entities_api` — no live stack needed.
Cover create-on-missing, update-on-existing, both `"Native"` and
`"Presto"` reads, absent-setting case, and the public `HLLType` alias.

Verified: full SDK unit suite — 438 passed, 2 skipped, 1 xfailed.

JIRA: CQ-2320
risk: low

Author: jaceksan

packages/gooddata-sdk/src/gooddata_sdk/__init__.py

@@ -137,7 +137,12 @@
     CatalogDeclarativeNotificationChannel,
     CatalogWebhook,
 )
-from gooddata_sdk.catalog.organization.service import CatalogOrganizationService
+from gooddata_sdk.catalog.organization.service import (
+    HLL_TYPE_SETTING_ID,
+    HLL_TYPE_SETTING_TYPE,
+    CatalogOrganizationService,
+    HLLType,
+)
 from gooddata_sdk.catalog.permission.declarative_model.dashboard_assignees import (
     CatalogAvailableAssignees,
     CatalogUserAssignee,

packages/gooddata-sdk/src/gooddata_sdk/catalog/organization/service.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import functools
-from typing import Any
+from typing import Any, Literal
 
 from gooddata_api_client.exceptions import NotFoundException
 from gooddata_api_client.model.declarative_export_templates import DeclarativeExportTemplates
@@ -35,6 +35,16 @@
 from gooddata_sdk.client import GoodDataApiClient
 from gooddata_sdk.utils import load_all_entities, load_all_entities_dict
 
+# Org-level setting controlling which HLL function family calcique uses when
+# generating SQL over HLL synopses. `Native` (default) emits StarRocks-native
+# `HLL_*` functions; `Presto` emits the Presto-compatible HLL function family
+# and assumes the StarRocks deployment carries the Presto HLL UDFs. Pick
+# `Presto` when synopses are produced by an upstream Presto pipeline (the
+# binary layout / hash family differ between the two).
+HLLType = Literal["Native", "Presto"]
+HLL_TYPE_SETTING_ID = "hyperLogLogType"
+HLL_TYPE_SETTING_TYPE = "HLL_TYPE"
+
 
 class CatalogOrganizationService(CatalogServiceBase):
     def __init__(self, api_client: GoodDataApiClient) -> None:
@@ -217,6 +227,40 @@ def delete_organization_setting(self, organization_setting_id: str) -> None:
                 f"This organization setting does not exist."
             )
 
+    def set_hll_type(self, value: HLLType) -> None:
+        """Set the organization-level HyperLogLog function family.
+
+        Idempotent: creates the `hyperLogLogType` setting if missing,
+        otherwise updates the existing one. The platform exposes this as
+        the `HLL_TYPE` org setting (gdc-nas `HLL_TYPE("hyperLogLogType",
+        SettingConfiguration.HyperLogLogType)`).
+
+        Args:
+            value: `"Native"` for StarRocks-native HLL functions (default
+                on the platform side), or `"Presto"` for Presto-compatible
+                HLL functions (use when synopses come from a Presto
+                pipeline; requires the Presto HLL UDFs registered in
+                StarRocks).
+        """
+        setting = CatalogOrganizationSetting.init(
+            setting_id=HLL_TYPE_SETTING_ID,
+            setting_type=HLL_TYPE_SETTING_TYPE,
+            content={"value": value},
+        )
+        try:
+            self.update_organization_setting(setting)
+        except ValueError:
+            self.create_organization_setting(setting)
+
+    def get_hll_type(self) -> HLLType | None:
+        """Return the current `hyperLogLogType` value, or `None` if unset."""
+        try:
+            setting = self.get_organization_setting(HLL_TYPE_SETTING_ID)
+        except NotFoundException:
+            return None
+        value = setting.attributes.content.get("value")
+        return value if value in ("Native", "Presto") else None
+
     def update_organization_setting(self, organization_setting: CatalogOrganizationSetting) -> None:
         """Update an organization setting.
 

packages/gooddata-sdk/tests/catalog/unit_tests/test_hll_type_setting.py

@@ -0,0 +1,115 @@
+# (C) 2026 GoodData Corporation
+"""Unit tests for the `set_hll_type` / `get_hll_type` org-setting helpers.
+
+These exercise the typed wrappers around the generic
+`CatalogOrganizationService.{create,update,get}_organization_setting`
+machinery; they don't need a live stack because the helpers' interesting
+logic is the create-or-update fallback and the JSON shape sent to the
+api-client.
+"""
+
+from __future__ import annotations
+
+import typing
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+from gooddata_api_client.exceptions import NotFoundException
+from gooddata_sdk import HLLType
+from gooddata_sdk.catalog.organization.service import (
+    HLL_TYPE_SETTING_ID,
+    HLL_TYPE_SETTING_TYPE,
+    CatalogOrganizationService,
+)
+
+
+def _make_service() -> tuple[CatalogOrganizationService, MagicMock]:
+    """Build a service whose entities-api side is fully mocked."""
+    fake_entities_api = MagicMock(name="EntitiesApi")
+    fake_client = SimpleNamespace(
+        entities_api=fake_entities_api,
+        layout_api=MagicMock(name="LayoutApi"),
+        actions_api=MagicMock(name="ActionsApi"),
+        user_management_api=MagicMock(name="UserManagementApi"),
+    )
+    service = CatalogOrganizationService(fake_client)  # type: ignore[arg-type]
+    return service, fake_entities_api
+
+
+def _captured_setting_payload(api: MagicMock, mock_call: MagicMock) -> dict:
+    """Pull out the `attributes` dict the SDK posted to the api-client."""
+    document = (
+        mock_call.call_args.kwargs.get("json_api_organization_setting_in_document") or mock_call.call_args.args[-1]
+    )
+    data = document.data
+    return {
+        "id": data.id,
+        "type": data.attributes.type,
+        "content": dict(data.attributes.content),
+    }
+
+
+class TestSetHllType:
+    def test_updates_existing_setting_when_present(self) -> None:
+        service, api = _make_service()
+        # update succeeds → no fallback to create
+        service.set_hll_type("Presto")
+        assert api.update_entity_organization_settings.call_count == 1
+        assert api.create_entity_organization_settings.call_count == 0
+        sent_id = api.update_entity_organization_settings.call_args.args[0]
+        assert sent_id == HLL_TYPE_SETTING_ID
+        sent = _captured_setting_payload(api, api.update_entity_organization_settings)
+        assert sent["id"] == HLL_TYPE_SETTING_ID
+        assert sent["type"] == HLL_TYPE_SETTING_TYPE
+        assert sent["content"] == {"value": "Presto"}
+
+    def test_creates_setting_when_missing(self) -> None:
+        service, api = _make_service()
+        api.update_entity_organization_settings.side_effect = NotFoundException(status=404, reason="not found")
+        service.set_hll_type("Native")
+        assert api.update_entity_organization_settings.call_count == 1
+        assert api.create_entity_organization_settings.call_count == 1
+        sent = _captured_setting_payload(api, api.create_entity_organization_settings)
+        assert sent["content"] == {"value": "Native"}
+
+
+class TestGetHllType:
+    def test_returns_native_when_set(self) -> None:
+        service, api = _make_service()
+        api.get_entity_organization_settings.return_value = SimpleNamespace(
+            data={
+                "id": HLL_TYPE_SETTING_ID,
+                "attributes": {"type": HLL_TYPE_SETTING_TYPE, "content": {"value": "Native"}},
+            }
+        )
+        assert service.get_hll_type() == "Native"
+
+    def test_returns_presto_when_set(self) -> None:
+        service, api = _make_service()
+        api.get_entity_organization_settings.return_value = SimpleNamespace(
+            data={
+                "id": HLL_TYPE_SETTING_ID,
+                "attributes": {"type": HLL_TYPE_SETTING_TYPE, "content": {"value": "Presto"}},
+            }
+        )
+        assert service.get_hll_type() == "Presto"
+
+    def test_returns_none_when_absent(self) -> None:
+        service, api = _make_service()
+        api.get_entity_organization_settings.side_effect = NotFoundException(status=404, reason="not found")
+        assert service.get_hll_type() is None
+
+    def test_returns_none_on_unrecognized_value(self) -> None:
+        service, api = _make_service()
+        api.get_entity_organization_settings.return_value = SimpleNamespace(
+            data={
+                "id": HLL_TYPE_SETTING_ID,
+                "attributes": {"type": HLL_TYPE_SETTING_TYPE, "content": {"value": "garbage"}},
+            }
+        )
+        assert service.get_hll_type() is None
+
+
+def test_hll_type_literal_is_exposed_on_public_api() -> None:
+    """The `HLLType` Literal is the canonical surface consumers should annotate against."""
+    assert typing.get_args(HLLType) == ("Native", "Presto")