Data Quality Gates Prerequisites

System requirements

Local environment capable of running Python 3.10-3.13 (any platform: Windows, macOS, Linux) or a virtual machine that follows the same requirements.

Python 3.13 support is available from DQ Gates version 1.1.1. Earlier versions support Python 3.9-3.12.
Network connectivity to your Ataccama ONE instance.
Ability to install Python packages and run Python scripts or Jupyter notebooks.

Prepare Ataccama ONE

Account and permissions

You’ll need:

An active Ataccama ONE account with access to the DQ firewalls that you want to use.
Access to Keycloak in your ONE instance, if you plan to use OIDC authentication.

Authentication setup

You can authenticate to ONE using the following authentication methods:

OpenID Connect (OIDC). Recommended for production environments.

This method uses Keycloak for identity and access management with the OIDC protocol. Follow the instructions in this section to configure Keycloak authentication using OpenID Connect:
1. Create a dedicated client in your Keycloak realm.
2. Assign required roles to the client.
3. Copy Ataccama ONE credentials for authentication.
Basic Authentication. Can be used for testing and debugging.

This method does not require creating a Keycloak client. Instead, provide the same credentials (username and password) you use to access Ataccama ONE via web interface.

Create Keycloak client

To create a new Keycloak client:

Navigate to your Keycloak Admin Console.
Select the Ataccama ONE realm: ataccamaone.
Select Clients > Create client.
Configure client settings:
- Client type: OpenID Connect.
- Client ID: A unique identifier (for example, dq-gates-client).
- Name: Client display name.
Select Next.
Configure authentication:
- Client authentication: Enable this option.
- Authorization: Leave turned off.
- Authentication flow: Enable Standard flow and Service accounts roles. Leave other fields disabled.
Select Next.
Keep the Login settings screen as it is, and select Save.

Assign required roles

To assign required roles to the Keycloak client:

Navigate to the Service accounts roles tab of your client.
Select Assign role.
Filter by realm roles and select the required role: MMM_admin.
Select Assign to confirm.

Copy Ataccama ONE credentials

Configure the following authentication credentials and provide them to the person responsible for the installation. These credentials are later used to fill in the .env file in the Configure the .env file step.

Ataccama credentials in the .env file

ATACCAMA_CLIENT_ID="myclient"
ATACCAMA_CLIENT_SECRET="secret"
ATACCAMA_KEYCLOAK_HOST="keycloak-worker.ataccama.cloud"
ATACCAMA_KEYCLOAK_REALM="myrealm"
# Alternatively, use Basic Auth
# ATACCAMA_CLIENT_USERNAME="ataccama username"
# ATACCAMA_CLIENT_PASSWORD="password"

To find the authentication credentials:

In Keycloak Admin Console, navigate to your client:
- Settings tab: Copy Client ID (ATACCAMA_CLIENT_ID).
- Credentials tab: Copy Client secret (ATACCAMA_CLIENT_SECRET).
Extract ATACCAMA_KEYCLOAK_HOST from your Keycloak Admin Console URL.

The format is: your-keycloak-host.domain.com/ (without https:// and /auth/).

For example: one-m2ne4.worker-01-cac1.prod.ataccama.link/.
For ATACCAMA_KEYCLOAK_REALM: Select the realm name from the dropdown in the upper-left corner of the Keycloak Admin Console.

Use the technical realm name, not the display name (for example, ataccamaone instead of Ataccama | ONE).

You can also find this name in Realm settings > Realm ID value.

Custom URL resolution for self-managed deployments

Available from DQ Gates version 1.1.0.

This section applies only to self-managed deployments with custom API endpoint URLs. Ataccama Cloud and Custom Ataccama Cloud deployments use standard URL resolution automatically.

If you’re unsure whether your deployment requires custom URL resolution, contact your system administrator.

By default, the client constructs API endpoint URLs by appending /graphql to your instance URL. If your self-managed deployment uses custom endpoint locations, implement a custom URL resolver after client initialization.

Custom URL resolver example

from ataccama_one.common.url import URLResolver

@dataclass
class CustomResolver(URLResolver):
    base_url: str
    mmm_url: str
    dqf_url: str

    def resolve_endpoint_url(self, endpoint_name):
        if isinstance(endpoint_name, str):
            return endpoint_name
        if endpoint_name == APIIdentifier.MMM:
            return self.mmm_url
        if endpoint_name in (APIIdentifier.DQF, APIIdentifier.DQ):
            return self.dqf_url
        raise ValueError(f"Unhandled endpoint {endpoint_name}")

resolver = CustomResolver(
    base_url=get_env_var("ATACCAMA_INSTANCE_URL"),
    mmm_url="https://custom-mmm.example.com/graphql",
    dqf_url="https://custom-dqf.example.com/graphql",
)

client = Client(
    platform_version=get_env_var("ATACCAMA_PLATFORM_VERSION"),
    url=resolver,
    auth=OpenIdConnectAuth(
        client_id=get_env_var("ATACCAMA_CLIENT_ID"),
        client_secret=get_env_var("ATACCAMA_CLIENT_SECRET"),
        keycloak_host=get_env_var("ATACCAMA_KEYCLOAK_HOST"),
        keycloak_realm=get_env_var("ATACCAMA_KEYCLOAK_REALM"),
    ),
)

Firewall filtering

Available from DQ Gates version 1.1.0.

This section applies to firewall-based runtimes such as local Python and Snowflake UDFs deployment.

Filter which firewalls to retrieve using AQL filters or Python predicates.

Using AQL filters. Filter firewalls when fetching them from Ataccama ONE.

AQL filter example

# Retrieve all firewalls (default)
firewalls = list(client.get_firewall_definitions())

# Retrieve only enabled firewalls
firewalls = list(client.get_firewall_definitions(filter="enabled=true"))

# Fetch firewalls whose name contains 'GATES' (case insensitive)
firewalls = list(client.get_firewall_definitions(filter="name LIKE 'GATES'"))

# Fetch firewalls with specific names (case sensitive)
firewalls = list(client.get_firewall_definitions(filter="name in ('CUSTOMERS', 'EMAILS')"))

# Combine predicates (enabled + deployment timestamp)
firewalls = list(
    client.get_firewall_definitions(
        filter="enabled=true and deploymentInfo.timestamp > '2025-09-01'",
    )
)

# Fetch by service IDs
firewalls = list(client.get_firewall_definitions(filter=["C10nSBQA78", "UID1Wy4ivg"]))

Using Python predicates. Filter the in-memory list after fetching.

Python predicates example

# Firewalls whose name starts with 'GATES'
firewalls_to_deploy = [fw for fw in firewalls if fw.name.startswith("GATES")]

# Firewalls that contain 'finance' in the description
firewalls_to_deploy = [
    fw for fw in firewalls
    if fw.description and 'finance' in fw.description.lower()
]

# Limit to specific firewall IDs
selected_ids = ["C10nSBQA78", "UID1Wy4ivg"]
firewalls_to_deploy = [fw for fw in firewalls if fw.firewall_id in selected_ids]

Next steps

Once you’ve completed the common prerequisites, continue with the installation guide for your environment:

Was this page useful?