acceldata-sdk-python 26.7.0__tar.gz

acceldata_sdk_python-26.7.0/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

acceldata_sdk_python-26.7.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 - present Acceldata Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

acceldata_sdk_python-26.7.0/MANIFEST.in

@@ -0,0 +1,2 @@
+global-include *.txt *.py *.md
+include LICENSE

acceldata_sdk_python-26.7.0/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: acceldata_sdk_python
+Version: 26.7.0
+Summary: Acceldata SDK Python
+Author-email: acceldata <apisupport@acceldata.io>
+License-Expression: MIT
+Keywords: acceldata-sdk-python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2
+Requires-Dist: requests
+Requires-Dist: requests-toolbelt
+Requires-Dist: semantic-version
+Provides-Extra: release
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Dynamic: license-file
+
+# Acceldata SDK for Python
+
+Documentation: https://docs.acceldata.io/documentation/acceldata-sdk-python

acceldata_sdk_python-26.7.0/README-catalog.md

@@ -0,0 +1,37 @@
+# Catalog guide
+
+Catalog APIs discover and monitor the data estate in ADOC. The SDK targets **Python 3.10+**; see the main [README](README.md) for install, `AdocClient` setup, and the short overview of generated versus hand-written packages.
+
+## Capabilities
+
+- **Datasources and crawlers** — list or load assemblies by name, id, or `AssetSourceType`; start crawlers; read crawler status.
+- **Assets** — resolve by numeric id or string uid; list `AssetType` definitions; read and extend metadata; fetch sample data.
+- **Profiling** — full, incremental, and selective runs with `AssetProfilingParams` and catalog `MarkerConfig` (ID, date-time, file-event bounds, and other wire variants); poll, cancel, and re-fetch profile requests.
+- **Policies** (separate from profiling jobs) — execute and monitor data quality, reconciliation, and cadence rules: [README-policies.md](README-policies.md).
+
+## Quick example
+
+```python
+from acceldata.client.adoc_client import AdocClient
+
+client = AdocClient(
+    url="https://<your-adoc-url>",
+    access_key="<your-access-key>",
+    secret_key="<your-secret-key>",
+)
+
+datasources = client.get_all_datasources()
+asset = client.get_asset("<asset_uid>")
+sample = asset.sample_data()
+
+print(asset.to_dict())
+```
+
+## Pick a task
+
+- **Comprehensive** catalog: datasources, filters, crawlers, assets, metadata, custom metadata, sample, profiling: [README-datasources-assets.md](README-datasources-assets.md)
+- **Policies** and execution: [README-policies.md](README-policies.md)
+
+## Next step
+
+Open the task-specific guide that matches the workflow; the same `AdocClient` instance can be reused across scripts.

acceldata_sdk_python-26.7.0/README-datasources-assets.md

@@ -0,0 +1,347 @@
+# Datasources, assets, metadata, and profiling
+
+This guide covers catalog operations with `AdocClient`: discover connections, run crawlers, resolve assets, work with metadata and sample data, and run profiling (full, incremental, and selective with marker configuration).
+
+- **Prerequisites:** [README](README.md) (install and client setup). Requires **Python 3.10+**.
+- **Data policies** (data quality, reconciliation, cadence): [README-policies.md](README-policies.md)
+
+ADOC can register many data source types (warehouses, lakes, messaging, and more). In code, use `AssetSourceType` to filter or interpret catalog responses.
+
+---
+
+## 1) Datasources
+
+Load one datasource by **name** or **numeric id**, optionally with extended **properties** on the returned object (or pass `properties=True` when loading).
+
+```python
+from acceldata.client.adoc_client import AdocClient
+from acceldata.models.sdk.catalog import AssetSourceType
+
+client = AdocClient(
+    url="https://<your-adoc-url>",
+    access_key="<your-access-key>",
+    secret_key="<your-secret-key>",
+)
+
+# By name, optional properties payload
+ds = client.get_datasource("snowflake_prod")
+ds = client.get_datasource("snowflake_prod", properties=True)
+ds = client.get_datasource(5)  # same as get_datasource_by_id(5)
+
+# All datasources
+all_sources = client.get_all_datasources()  # alias: get_datasources() with no filter
+
+# Filter by source type
+snowflake_only = client.get_datasources(AssetSourceType.SNOWFLAKE)
+```
+
+A fetch returns a `DatasourceResource` with `id`, `name`, and `source_type`. For the full API-shaped payload (for logging or debugging), use `to_dict()` rather than reaching into internal fields. Use `refresh(properties=...)` to reload from the catalog.
+
+```python
+print(ds.to_dict())
+```
+
+---
+
+## 2) Crawler operations
+
+Crawler start and status are available from the **datasource object** (preferred) or by **name** on the client. Both support optional `RetryConfig` for transient HTTP/transport issues.
+
+```python
+# Using a DatasourceResource
+ds = client.get_datasource("my_datasource")
+start = ds.start_crawler()
+status = ds.get_crawler_status()
+
+# Or by name on the client
+client.start_crawler("my_datasource")
+client.get_crawler_status("my_datasource")
+```
+
+---
+
+## 3) Assets and asset types
+
+### Resolve an asset
+
+Pass a **string uid** (for example `Feature_bag_datasource.feature_1`) or a **numeric id** (`int`, or a string of digits, which is treated as an id, not a uid).
+
+```python
+# By numeric id
+asset = client.get_asset(1)
+
+# By uid
+asset = client.get_asset("Feature_bag_datasource.feature_1")
+```
+
+The result is an `AssetResource`. `asset.to_dict()` returns the full payload as plain data.
+
+```python
+print(asset.to_dict())
+```
+
+### List asset type definitions
+
+```python
+types = client.get_all_asset_types()  # alias of get_asset_types()
+```
+
+Each entry is a catalog `AssetType` (name, id, and related fields as returned by the API).
+
+---
+
+## 4) Metadata, custom metadata, and sample data
+
+```python
+from acceldata.models.sdk.catalog import CustomAssetMetadata
+
+asset = client.get_asset("my_datasource.my_table")
+
+# Fetched metadata (as stored for the asset)
+md = asset.get_metadata()
+# Or: client.get_asset_metadata(asset_id)
+
+# Merge custom key/value pairs (string values; merged then POSTed)
+asset.add_custom_metadata(
+    [
+        CustomAssetMetadata("owner", "analytics"),
+        CustomAssetMetadata("pii", "true"),
+    ]
+)
+# Or pass a flat mapping from the client: client.add_custom_metadata(asset_id, {"owner": "analytics"})
+
+# Sample data (default): trigger async job and block by polling until not IN_PROGRESS
+sample = asset.sample_data(sync=True)  # sync=True is the default
+# Or: client.sample_data(asset_id, sync=True)
+
+# Non-blocking mode: trigger async job and return immediately with request_id
+initial = asset.sample_data(sync=False)
+# Or: initial = client.sample_data(asset_id, sync=False)
+request_id = initial.request_id if initial is not None else None
+
+# With an async `request_id`, poll the result
+if request_id:
+    result = client.get_sample_data_result(request_id)
+```
+
+---
+
+## 5) Profiling: parameters and modes
+
+Catalog profiling is driven by `AssetProfilingParams`, which only sets the catalog profiling type and optional `markerConfig` (other start-profile fields use catalog defaults inside `to_start_profiling_request()`).
+
+| Field | Type | When required |
+|-------|------|---------------|
+| `profiling_type` | `ProfilingType` | Always (`FULL`, `INCREMENTAL`, or `SELECTIVE`). |
+| `marker_config` | `MarkerConfig` (optional) | Required for `SELECTIVE`. Also required for `INCREMENTAL` (per validation: incremental runs need a marker on the request). Omitted for most `FULL` runs. |
+
+`ExecutionType` (from the same profiling module as `ProfilingType`) mirrors the same string values as `ProfilingType` for execution-oriented typing in application code.
+
+**Preferred pattern for starting a run:** use `AdocClient.profile_asset` to obtain a `ProfileRequestResource` with `get_status()` and `cancel()`. Pass optional `transient_retry=RetryConfig(...)` to retry transient HTTP/transport failures; default retry status codes include **HTTP 409** (for example, profile already running).
+
+`profile_asset(..., sync=False)` (default) is fire-and-forget. It triggers profiling and immediately returns the initial request (with `id`).
+
+`profile_asset(..., sync=True)` uses the returned request id to keep checking profile status until it reaches a terminal state.
+
+```python
+from acceldata.client.transient_retry import RetryConfig
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+
+params = AssetProfilingParams(profiling_type=ProfilingType.FULL)
+# Async fire-and-forget (default)
+profile = client.profile_asset(
+    123,
+    params,
+    sync=False,
+    # transient_retry=RetryConfig(max_attempts=6, initial_interval_seconds=30.0, max_interval_seconds=30.0),
+)
+print(profile.to_dict())
+
+# Sync mode: block until terminal status by polling with request id
+completed_profile = client.profile_asset(
+    123,
+    params,
+    sync=True,
+)
+print(completed_profile.to_dict())
+```
+
+`AssetResource.start_profile(profiling_params=..., sync=...)` returns the same `ProfileRequestResource` shape (status and cancel helpers):
+
+```python
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+
+res = asset.start_profile(
+    AssetProfilingParams(profiling_type=ProfilingType.FULL),
+    sync=False,  # default: async fire-and-forget
+)
+print(res.to_dict())
+details = res.get_status()
+res.cancel()  # may return None for terminal/no-op cases, see API behavior
+```
+
+**Latest status and lookup by request id**
+
+```python
+# Latest status for the asset — response type is MiniProfileRequest
+latest = client.get_latest_profile_status(asset_id=123)
+# Or: asset.get_latest_profile_status() on an AssetResource
+
+# Specific profile request by (asset_id, req_id) — also exposed as get_profile_status
+by_req = client.get_profile_request_details(asset_id=123, req_id=456)
+# Or: client.get_profile_status(123, 456)
+```
+
+**Cancel** by request id (when only the id is available, not a resource instance):
+
+```python
+client.cancel_profile(profile_req_id)
+```
+
+`ProfileRequestResource` delegates cancel and status to these client/service methods. Transient read retries for crawler and profile calls can be configured with `RetryConfig` where the method allows it.
+
+---
+
+## 5a) Trigger full profiling
+
+Runs the configured full scan for the asset. The snippet below assumes a `client` from [section 1](#1-datasources).
+
+```python
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+
+asset = client.get_asset("my_datasource.my_table")
+params = AssetProfilingParams(profiling_type=ProfilingType.FULL)
+client.profile_asset(asset.id, params)
+```
+
+---
+
+## 5b) Trigger incremental profiling
+
+Use when the asset’s catalog configuration defines an incremental strategy; a **marker is required** on the request. For an id-column incremental strategy, use **`id_marker_config`**. For other strategies, use the **`*_marker_config` helper** in `acceldata.services.marker_config` that matches the generated class you need (e.g. **`date_time_marker_config`** for `DateTimeMarkerConfig`, **`file_marker_config`** for `FileMarkerConfig`—same naming pattern as `BoundsDateTimeMarkerConfig` → **`bounds_date_time_marker_config`**). You can also set `type` yourself using **`marker_type_for`** or **`API_TYPE_BY_MARKER_CLASS`**, or call **`as_marker_config`**, which can fix a wrong `type` on a typed model instance. `AssetProfilingParams.marker_config` also accepts a generated branch instance or a `MarkerConfig` wrapper; the client normalizes them when the request is sent.
+
+The snippet assumes a configured `AdocClient` `client` (see the start of this guide). As with full profiling ([section 5](#5-profiling-parameters-and-modes)), `profile_asset` accepts `sync=True` to poll until a terminal status and `transient_retry=RetryConfig(...)` for transient HTTP/transport retries (including while polling in sync mode).
+
+```python
+from acceldata.client.transient_retry import RetryConfig
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+from acceldata.services.marker_config import id_marker_config
+
+asset = client.get_asset("my_datasource.my_table")
+params = AssetProfilingParams(
+    profiling_type=ProfilingType.INCREMENTAL,
+    marker_config=id_marker_config(
+        id_column_name="pk_col",
+        initial_offset=0,
+    ),
+)
+client.profile_asset(
+    asset.id,
+    params,
+    sync=False,  # default: async; use sync=True to block until terminal
+    # transient_retry=RetryConfig(max_attempts=6, initial_interval_seconds=30.0, max_interval_seconds=30.0),
+)
+```
+
+---
+
+## 5c) Trigger selective profiling (bounds-style markers)
+
+Selective profiling must include a **marker**. For id-bounded slices use `bounds_id_marker_config`; for date- or file-event–bounded slices use **`bounds_date_time_marker_config`** or **`bounds_file_event_marker_config`**. Each example below assumes a configured `client` from [section 1](#1-datasources). The same `sync` and `transient_retry` options as in [section 5](#5-profiling-parameters-and-modes) apply to `profile_asset` for selective runs.
+
+**ID-bounded (monotonic / range column)**
+
+```python
+from acceldata.client.transient_retry import RetryConfig
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+from acceldata.services.marker_config import bounds_id_marker_config
+
+asset = client.get_asset("my_datasource.my_table")
+params = AssetProfilingParams(
+    profiling_type=ProfilingType.SELECTIVE,
+    marker_config=bounds_id_marker_config(
+        id_column_name="ID",
+        from_id=0,
+        to_id=1000,
+    ),
+)
+client.profile_asset(
+    asset.id,
+    params,
+    sync=False,
+    # transient_retry=RetryConfig(max_attempts=6, initial_interval_seconds=30.0, max_interval_seconds=30.0),
+)
+```
+
+**DateTime-bounded (column, format, timezone, optional range strings)**
+
+```python
+from acceldata.client.transient_retry import RetryConfig
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+from acceldata.services.marker_config import bounds_date_time_marker_config
+
+asset = client.get_asset("my_datasource.my_table")
+params = AssetProfilingParams(
+    profiling_type=ProfilingType.SELECTIVE,
+    marker_config=bounds_date_time_marker_config(
+        date_column_name="TO_DATE",
+        format="yyyy-MM-dd",
+        time_zone_id="Asia/Calcutta",
+        from_date="2023-07-01 00:00:00.000",
+        to_date="2024-07-14 23:59:59.999",
+    ),
+)
+client.profile_asset(
+    asset.id,
+    params,
+    sync=False,
+    # transient_retry=RetryConfig(max_attempts=6, initial_interval_seconds=30.0, max_interval_seconds=30.0),
+)
+```
+
+**File event–based bounds**
+
+```python
+from acceldata.client.transient_retry import RetryConfig
+from acceldata.models.sdk.catalog import AssetProfilingParams, ProfilingType
+from acceldata.services.marker_config import bounds_file_event_marker_config
+
+asset = client.get_asset("my_datasource.my_table")
+params = AssetProfilingParams(
+    profiling_type=ProfilingType.SELECTIVE,
+    marker_config=bounds_file_event_marker_config(
+        date_column_name="ingest_date",
+        time_zone_id="Asia/Calcutta",
+        from_date="2019-04-01 00:00:00.000",
+        to_date="2024-07-16 23:59:59.999",
+    ),
+)
+client.profile_asset(
+    asset.id,
+    params,
+    sync=False,
+    # transient_retry=RetryConfig(max_attempts=6, initial_interval_seconds=30.0, max_interval_seconds=30.0),
+)
+```
+
+For partitioning, file-based markers, Pub/Sub, offsets, and similar cases, use the matching `*_marker_config` helper in `acceldata.services.marker_config` (each pairs with a generated `*MarkerConfig` class—see **`API_TYPE_BY_MARKER_CLASS`**), or build the model with an explicit `type=`, then pass the instance the same way as in the examples above.
+
+---
+
+## 6) Relationship to other SDK areas
+
+- **Data quality, reconciliation, and cadence (freshness) policies** are separate catalog rule executions; start and poll them with `execute_policy`, `Executor`, and the helpers in [README-policies.md](README-policies.md).
+
+## Next step
+
+- Policy execution: [README-policies.md](README-policies.md)  
+- Catalog index: [README-catalog.md](README-catalog.md)  
+
+---
+
+## Operational notes
+
+- For **long or flaky** catalog calls, pass `transient_retry=RetryConfig(...)` where the client method supports it.  
+- Use **defaults** and match **marker** discriminators to the target ADOC environment; invalid combinations raise validation errors (for example, missing `markerConfig` for `SELECTIVE`).  
+
+When wiring transient retries, import `RetryConfig` next to the `AdocClient` setup imports.

acceldata_sdk_python-26.7.0/README-historical-pipeline.md

@@ -0,0 +1,192 @@
+# Historical pipeline load
+
+This guide covers backfilling past pipeline executions with explicit timestamps.
+
+For install and `AdocClient` setup, see [README](README.md). For normal real-time execution, use the [Pipelines guide](README-pipeline.md).
+
+## When this guide helps
+
+- Replaying past runs into ADOC
+- Migrating existing pipeline history
+- Aligning event and run times with original execution time
+
+## Historical flow
+
+1. Create pipeline with explicit creation time
+2. Create run with explicit `started_at`
+3. Create span with `with_explicit_time=True`
+4. Create a job bounded by span and fetch that span by UID
+5. Create child spans under the fetched job span
+6. Start, send events, and end spans with explicit timestamps
+7. Complete run with explicit `finished_at`
+
+## Minimal example
+
+```python
+from datetime import datetime, timedelta
+
+from acceldata.client.adoc_client import AdocClient
+from acceldata.models.api.pipeline.meta import Meta
+from acceldata.models.sdk.pipeline.create_job_input import CreateJobInput, JobInputOutputRef
+from acceldata.models.sdk.pipeline import GenericEvent, PipelineRunResult, PipelineRunStatus
+from acceldata.models.sdk.pipeline.create_pipeline_input_request import (
+    CreatePipelineInputRequest,
+)
+from acceldata.models.sdk.pipeline.pipeline_run_input import PipelineRunInput
+
+client = AdocClient(
+    url="https://<your-adoc-url>",
+    access_key="<your-access-key>",
+    secret_key="<your-secret-key>",
+)
+
+base_time = datetime(2024, 1, 15, 10, 0, 0)
+
+# 1) Create pipeline with historical createdAt
+pipeline = client.create_pipeline(
+    CreatePipelineInputRequest(
+        uid="historical_customers_etl",
+        name="Historical customers ETL",
+        meta=Meta(owner="data-team", team="analytics", code_location="..."),
+        createdAt=base_time,
+    )
+)
+
+# 2) Create run with historical start time
+run_start = base_time + timedelta(hours=1)
+run = pipeline.create_pipeline_run(PipelineRunInput(started_at=run_start))
+# `run` is a PipelineRunResource.
+print(run.to_dict())
+
+# 3) Create span with explicit-time mode (no auto-start)
+root_span = run.create_root_span(
+    uid="historical_customers_root",
+    with_explicit_time=True,
+)
+
+# 4) Create a bounded job span and load it by UID
+job = run.create_job(
+    CreateJobInput(
+        uid="historical_customers_transform",
+        name="Historical customers transform",
+        description="Backfilled transform job with explicit span timing.",
+        pipeline_run_id=run.id,
+        bounded_by_span=True,
+        with_explicit_time=True,
+        span_uid="historical_customers_transform_span",
+        inputs=[JobInputOutputRef(asset_uid="s3_ds.staging.customers_raw_snapshot")],
+        outputs=[JobInputOutputRef(asset_uid="snowflake_ds.warehouse.customers_curated")],
+        meta=Meta(owner="data-team", team="analytics", code_location="..."),
+        context={"replay": "historical_customers_etl"},
+    )
+)
+job_span = run.get_span("historical_customers_transform_span")  # explicit source for child spans below
+
+alternative_job = run.create_job(
+    CreateJobInput(
+        uid="historical_customers_enrich",
+        name="Historical customers enrich",
+        description="Unbounded job bound to a manually created child span.",
+        pipeline_run_id=run.id,
+        bounded_by_span=False,
+        with_explicit_time=True,
+        inputs=[JobInputOutputRef(asset_uid="snowflake_ds.warehouse.customers_curated")],
+        outputs=[JobInputOutputRef(asset_uid="snowflake_ds.warehouse.customers_enriched")],
+        meta=Meta(owner="data-team", team="analytics", code_location="..."),
+        context={"replay": "historical_customers_etl", "variant": "manual_span"},
+    )
+)
+
+# Alternative with bounded_by_span=False: create and bind span explicitly.
+alternative_job_span = job_span.create_child_span(
+    uid="historical_customers_enrich_span",
+    associated_job_uids=[alternative_job.uid],
+    with_explicit_time=True,
+)
+
+# 5) Start, send events, and end spans at chosen timestamps
+root_span_start = run_start + timedelta(seconds=10)
+job_span_start = run_start + timedelta(minutes=1)
+alternative_start = run_start + timedelta(minutes=1, seconds=30)
+alternative_event = run_start + timedelta(minutes=1, seconds=45)
+alternative_end = run_start + timedelta(minutes=1, seconds=55)
+validate_start = run_start + timedelta(minutes=2)
+validate_event = run_start + timedelta(minutes=3)
+validate_end = run_start + timedelta(minutes=4)
+publish_start = run_start + timedelta(minutes=5)
+publish_event = run_start + timedelta(minutes=6)
+publish_end = run_start + timedelta(minutes=8)
+job_span_end = run_start + timedelta(minutes=9)
+root_span_end = run_start + timedelta(minutes=15)
+run_end = run_start + timedelta(minutes=20)
+
+root_span.start(created_at=root_span_start)
+job_span.start(created_at=job_span_start)
+alternative_job_span.start(created_at=alternative_start)
+alternative_job_span.send_event(
+    GenericEvent(
+        event_uid="historical_enrich_completed",
+        context_data={"rows_enriched": 11800},
+        created_at=alternative_event,
+    )
+)
+alternative_job_span.end(created_at=alternative_end)
+
+validate_span = job_span.create_child_span(
+    uid="historical_customers_validate_span",
+    associated_job_uids=[job.uid],
+    with_explicit_time=True,
+)
+validate_span.start(created_at=validate_start)
+validate_span.send_event(
+    GenericEvent(
+        event_uid="historical_validate_completed",
+        context_data={"rows_validated": 12000},
+        created_at=validate_event,
+    )
+)
+validate_span.end(created_at=validate_end)
+
+publish_span = job_span.create_child_span(
+    uid="historical_customers_publish_span",
+    associated_job_uids=[job.uid],
+    with_explicit_time=True,
+)
+publish_span.start(created_at=publish_start)
+publish_span.send_event(
+    GenericEvent(
+        event_uid="historical_publish_completed",
+        context_data={"rows_loaded": 11800},
+        created_at=publish_event,
+    )
+)
+publish_span.end(created_at=publish_end)
+job_span.end(created_at=job_span_end)
+root_span.end(created_at=root_span_end)
+
+# 5) Complete run with explicit finish time
+run.update_pipeline_run(
+    result=PipelineRunResult.SUCCESS,
+    status=PipelineRunStatus.COMPLETED,
+    finished_at=run_end,
+)
+```
+
+`JobInputOutputRef(asset_uid=...)` must use dot notation (`<data_source_uid>.<asset_uid>`). The value is available from the Asset page in the ADOC UI.
+
+## Critical rules
+
+- Always set `with_explicit_time=True` for spans in historical mode
+- Always call `start(created_at=...)` explicitly for those spans
+- Always set `created_at` for important events
+- Always set `finished_at` when completing the run
+
+## Common mistakes
+
+- Forgetting to call `start(created_at=...)` before sending events or ending spans
+- Mixing historical and current-time values in one run
+- Completing the run without `finished_at`
+
+## Next step
+
+When multiple scripts contribute to the same historical run, combine this flow with [Pipeline continuation ID](README-pipeline-continuation-id.md).