# Where to Start

Use this package to run SHACL validation locally, deploy validation infrastructure to CDF, and run the validation pipeline. The flow below matches the environment notebook (e.g. `config/environments/cog-sail/test_cogsail_cognite_data_quality.ipynb`).

## Quick Start Guide

### 1. Installation

```bash
pip install cognite-data-quality
```

After install, restart your kernel or interpreter so imports pick up the package.

### 2. Setup credentials

Create a TOML file with your CDF credentials (e.g. `cog-sail.toml`):

```toml
[cognite]
project = "your-project"
client_id = "your-client-id"
client_secret = "your-client-secret"
```

Load the client:

```python
from pathlib import Path
import cognite_data_quality

client = cognite_data_quality.load_cognite_client_from_toml("cog-sail.toml")
client.config.timeout = 300  # Optional: for large function deployments
```

### 3. Development: test rules locally

Use `run_validation()` to validate instances from DMS without deploying:

```python
from pathlib import Path
import cognite_data_quality

# Path to SHACL rules (TTL) and data model config
rules_path = Path("shacl_rules/smallboat_shacl_rules.ttl")

result = cognite_data_quality.run_validation(
    client=client,
    rules_path=str(rules_path),
    rules_format="ttl",
    datamodel=cognite_data_quality.DataModelConfig(
        space="sailboat", external_id="sailboat", version="v1"
    ),
    instance_space="sailboat",
    post_to_records=True,
    records_config=cognite_data_quality.RecordsConfig(
        stream_id="dq_validation_stream",
        rule_set_id="SailboatSHACLv1",
        rule_set_version="1.0",
    ),
    limit=10,
    print_output=True,
)

print("Instance count:", result.instance_count)
print("Violations:", len([v for v in result.violations if (v.resultSeverity or "").endswith("Violation")]))
```

You can also use a YAML view config for `rules_path` with `rules_format="yaml"` so datamodel and instance space come from the config.

### 4. Production: deploy infrastructure

Deploy all validation infrastructure (containers, function, workflows, triggers):

```python
from pathlib import Path
import cognite_data_quality

config_root = Path(".")  # Directory containing settings.yaml
settings_path = config_root / "settings.yaml"
views_dir = config_root / "views"

# Credentials for function (orchestrator needs them for triggers)
creds = client.config.credentials
function_secrets = None
if hasattr(creds, "client_id") and hasattr(creds, "client_secret"):
    function_secrets = {
        "client-id": creds.client_id,
        "client-secret": creds.client_secret,
    }

result = cognite_data_quality.deploy_validation_infrastructure(
    client=client,
    settings_path=settings_path,
    views_dir=views_dir,
    function_secrets=function_secrets,
    dry_run=False,
    force=False,
)
```

This ensures Records, OrchestrationState, and FunctionValidationState containers; deploys the monitoring data model and views; deploys the unified validation function and instance (and optional time series) workflows and triggers.

### 5. Deploy validation pipeline (historic + incremental)

Run the full validation pipeline for a view (historic partitions, sync trigger, monitor schedule):

```python
result = cognite_data_quality.deploy_validation_pipeline(
    client,
    settings_path=str(settings_path),
    view_external_id="LargeBoat",  # or "SmallBoat", "NavigationAid", etc.
    wait=True,
)
print("Orchestration ID:", result.get("orchestration_id"))
print("Partitions triggered:", result.get("partitions_triggered"), "/", result.get("partition_count"))
```

### 6. Invoke deployed functions

Call the deployed function from Python:

```python
from cognite_data_quality import call_validate_instances_shacl

result = call_validate_instances_shacl(client, data)
```

Or use `call_validation(client, validation_type="instance", data=data)` for the unified entry point.

## Next steps

- **[Config](config.md):** TOML and view config
- **[Notebook](notebook.md):** Example notebook location and snippets
- **[Deploy](../usage/deploy.md):** Deployment options in detail
- **[Run validation](../usage/run_validation.md):** Parameters and Records
- **[Invoke](../usage/invoke.md):** Invoke helpers and payloads
- **[API Reference](../api/deploy.md):** Full API
