Skip to content

Datasets

Generated by scripts/generate_docs.py (scripts/regen_docs.sh). Do not edit by hand.

Methods of client.datasets (reportnet_api.resources.datasets_ext.DatasetsResource). Every method also exists on AsyncReportnetClient as await a_client.datasets.<name>(...) with the same arguments. Roles are copied from the API spec; where it states none, this page says so rather than guessing.

Back to index

Methods

check_import_process

Test import file to dataset data (Large files)

HTTP: GET /dataset/checkImportProcess/{datasetId}

Call: client.datasets.check_import_process(...) (async client: await a_client.datasets.check_import_process(...))

Argument Type Required Default Description
dataset_id int yes Dataset id

Returns: CheckLockVO

Allowed roles:

Dataset type Roles
Reporting dataset LEAD REPORTER, REPORTER WRITE, NATIONAL COORDINATOR
Data collection CUSTODIAN, STEWARD
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

Live-tested notes:

  • The lock is unreliable as a 'safe to proceed' signal: it stayed importInProgress=True for 6+ minutes after an import whose completion was confirmed elsewhere. Prefer get_import_related_statistics() or import_file_and_wait(). It also said importInProgress=False while an import job was running, so it is unreliable in both directions.

convert_iceberg_to_parquet_tables

convertIcebergToParquetTables

HTTP: POST /dataset/convertIcebergToParquetTables/{datasetId}

Call: client.datasets.convert_iceberg_to_parquet_tables(...) (async client: await a_client.datasets.convert_iceberg_to_parquet_tables(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int yes
provider_id int \| None no None
table_schema_ids list[str] \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

convert_parquet_to_iceberg_tables

convertParquetToIcebergTables

HTTP: POST /dataset/convertParquetToIcebergTables/{datasetId}

Call: client.datasets.convert_parquet_to_iceberg_tables(...) (async client: await a_client.datasets.convert_parquet_to_iceberg_tables(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int yes
provider_id int \| None no None
table_schema_ids list[str] \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

create_empty_tables_v3

createEmptyTablesV3

HTTP: POST /dataset/{datasetId}/createEmptyTablesV3

Call: client.datasets.create_empty_tables_v3(...) (async client: await a_client.datasets.create_empty_tables_v3(...))

Argument Type Required Default Description
dataset_id int yes
table_schema_id str \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

create_public_files

createPublicFiles

HTTP: POST /dataset/createPublicFiles

Call: client.datasets.create_public_files(...) (async client: await a_client.datasets.create_public_files(...))

Argument Type Required Default Description
dataflow_id int yes
create_reference_dataset bool \| None no None
provider_id int \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

delete_attachment

Delete attachment by field id

HTTP: DELETE /dataset/v1/{datasetId}/field/{fieldId}/attachment

Call: client.datasets.delete_attachment(...) (async client: await a_client.datasets.delete_attachment(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
field_id str yes Field id
dataflow_id int \| None no None Dataflow id
field_name str \| None no None Field name
file_name str \| None no None File name
provider_id int \| None no None Provider id
record_id str \| None no None Record id
table_schema_name str \| None no None Table schema name

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset LEAD REPORTER, REPORTER WRITE, NATIONAL COORDINATOR
Data collection CUSTODIAN, STEWARD, OBSERVER
Test dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

delete_dataset_data

Delete dataset data

HTTP: DELETE /dataset/v1/{datasetId}/deleteDatasetData

Call: client.datasets.delete_dataset_data(...) (async client: await a_client.datasets.delete_dataset_data(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
dataflow_id int \| None no None Dataflow id
delete_prefilled_tables bool \| None no None Delete prefilled tables
provider_id int \| None no None Provider id
preparation_code str \| None no None

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset REPORTER WRITE, LEAD REPORTER
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

preparation_code (sent as preparationCode; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • Irreversible; deliberately not run against production. Not verified live.

delete_import_table

Deletes all data in one table. Hidden legacy (unversioned) alias of delete_table_data() (/dataset/v1/{id}/deleteTableData/{tableId}): DatasetControllerImpl#deleteImportTableLegacy just calls deleteTableData. The Reportnet FME integration uses this route. Destructive and not undoable. Returns None (the controller is void).

HTTP: DELETE /dataset/{dataset_id}/deleteImportTable/{table_schema_id}

Call: client.datasets.delete_import_table(...) (async client: await a_client.datasets.delete_import_table(...))

Argument Type Required Default Description
dataset_id int yes
table_schema_id str yes
dataflow_id int \| None no None
provider_id int \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

Role rules are the same as delete_table_data(); the hidden route also accepts an ApiKey (dataflow_id/provider_id feed that check). Untested live: the backend source audited is older than production.

Live-tested notes:

  • Hidden legacy alias of delete_table_data. Mocked tests only; not tested live because it is destructive.

delete_table_data

Delete table data

HTTP: DELETE /dataset/v1/{datasetId}/deleteTableData/{tableSchemaId}

Call: client.datasets.delete_table_data(...) (async client: await a_client.datasets.delete_table_data(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
table_schema_id str yes Table schema id
dataflow_id int \| None no None Dataflow id
provider_id int \| None no None Provider id
preparation_code str \| None no None

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset REPORTER WRITE, LEAD REPORTER
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

preparation_code (sent as preparationCode; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

download_imported_file

Downloads a specific imported file for a given dataset and a given filename

HTTP: GET /dataset/download-imported-file

Call: client.datasets.download_imported_file(...) (async client: await a_client.datasets.download_imported_file(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int yes
file_name str yes
dest str \| os.PathLike[str] yes

Returns: None

Allowed roles:

Not stated in the API spec.

Live-tested notes:

  • ApiKey got 403; a Bearer Custodian/Steward credential passed the role gate and got a 500 'no import directory' on the scratch dataset (no data to download).

duplicate_field_value_exists

duplicateFieldValueExists

HTTP: POST /dataset/duplicateFieldValueExists/{datasetId}

Call: client.datasets.duplicate_field_value_exists(...) (async client: await a_client.datasets.duplicate_field_value_exists(...))

Argument Type Required Default Description
dataset_id int yes
table_schema_id str yes
field_vo FieldVO yes

Returns: bool

Allowed roles:

Not stated in the API spec.

etl_export_dataset

Export data by dataset id

HTTP: GET /dataset/v1/{datasetId}/etlExport

Call: client.datasets.etl_export_dataset(...) (async client: await a_client.datasets.etl_export_dataset(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
dest str \| os.PathLike[str] yes
column_name str \| None no None Filter column name
data_provider_codes str \| None no None Data provider codes
filter_value str \| None no None Filter value
limit int \| None no None
offset int \| None no None
provider_id int \| None no None Provider id
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Paging: live-tested (production and sandbox), offset is a 0-based ROW offset, not a page number: offset=0 (or omitted) starts at the first row, then step by limit (offset=limit, 2*limit, ...); an offset at or past the total returns no records. Sending offset=1 skips the first row and overlaps the next page. (The backend source on develop reads as a 1-based page number, limit * offset - limit; the deployed builds do not follow it.) Keep the same limit on every call; limit defaults to 10000 server-side. Do not use FME's 'new' paging mode on this backend.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • The ETL family is gated separately from the documented roles: a Bearer Custodian/Steward credential got 403 on the scratch dataset even though the docstring lists those roles, while an ApiKey worked for the exports. Do not assume a Bearer role level predicts ETL access; unverified per credential.
  • Synchronous export (worked live with an ApiKey). offset is a 0-based row offset, not a page number (live-tested on production and the sandbox, 2026-10-27: step by limit from 0).

etl_export_dataset_v2

Export data by dataset id

HTTP: GET /dataset/v2/etlExport/{datasetId}

Call: client.datasets.etl_export_dataset_v2(...) (async client: await a_client.datasets.etl_export_dataset_v2(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
dest str \| os.PathLike[str] yes
column_name str \| None no None Filter column name
data_provider_codes str \| None no None Data provider codes
filter_value str \| None no None Filter value
limit int \| None no None
offset int \| None no None
provider_id int \| None no None Provider id
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Paging: live-tested (production and sandbox), offset is a 0-based ROW offset, not a page number: offset=0 (or omitted) starts at the first row, then step by limit (offset=limit, 2*limit, ...); an offset at or past the total returns no records. Sending offset=1 skips the first row and overlaps the next page. (The backend source on develop reads as a 1-based page number, limit * offset - limit; the deployed builds do not follow it.) Keep the same limit on every call; limit defaults to 10000 server-side. Do not use FME's 'new' paging mode on this backend.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • The ETL family is gated separately from the documented roles: a Bearer Custodian/Steward credential got 403 on the scratch dataset even though the docstring lists those roles, while an ApiKey worked for the exports. Do not assume a Bearer role level predicts ETL access; unverified per credential.
  • Synchronous export (worked live with an ApiKey). offset is a 0-based row offset, not a page number (live-tested on production and the sandbox, 2026-10-27: step by limit from 0).

etl_export_dataset_with_job

Export data by dataset id

HTTP: GET /dataset/v3/etlExport/{datasetId}

Call: client.datasets.etl_export_dataset_with_job(...) (async client: await a_client.datasets.etl_export_dataset_with_job(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
column_name str \| None no None Filter column name
data_provider_codes str \| None no None Data provider codes
filter_value str \| None no None Filter value
limit int \| None no None
offset int \| None no None
provider_id int \| None no None Provider id
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Async job-based export: returns job metadata, e.g. {'pollingUrl': ..., 'status': 'Preparing file'}, never the exported data. Poll pollingUrl (Orchestrator, outside this client's spec coverage) until the job completes; this client has no polling helper.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • Async job variant: returns job metadata (pollingUrl), never the data. Use the matching *_to_file helper or jobs.wait_for_job to wait for it.
  • Only the job start was tested live; the finished job's download was not.

etl_export_zip_csv

Export data by dataset id

HTTP: GET /dataset/v4/etlExport/{datasetId}

Call: client.datasets.etl_export_zip_csv(...) (async client: await a_client.datasets.etl_export_zip_csv(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
data_provider_codes str \| None no None Data provider codes
include_attachments bool \| None no None
provider_id int \| None no None Provider id
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Async job-based export: returns job metadata, e.g. {'pollingUrl': ..., 'status': 'Preparing file'}, never the exported data. Poll pollingUrl (Orchestrator, outside this client's spec coverage) until the job completes; this client has no polling helper.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • Async job variant: returns job metadata (pollingUrl), never the data. Use the matching *_to_file helper or jobs.wait_for_job to wait for it.
  • The v4 CSV export ran end to end with an ApiKey (~75s, valid ZIP); a Bearer Custodian/Steward credential got 403.

etl_export_zip_parquet

Export parquet data by dataset id

HTTP: GET /dataset/v5/etlExport/{datasetId}

Call: client.datasets.etl_export_zip_parquet(...) (async client: await a_client.datasets.etl_export_zip_parquet(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
data_provider_codes str \| None no None Data provider codes
include_attachments bool \| None no None
provider_id int \| None no None Provider id
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Async job-based export: returns job metadata, e.g. {'pollingUrl': ..., 'status': 'Preparing file'}, never the exported data. Poll pollingUrl (Orchestrator, outside this client's spec coverage) until the job completes; this client has no polling helper.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • Async job variant: returns job metadata (pollingUrl), never the data. Use the matching *_to_file helper or jobs.wait_for_job to wait for it.
  • The v5 Parquet export ran end to end with an ApiKey (~31s, valid ZIP).

etl_import_dataset

Import data by dataset id

HTTP: POST /dataset/v1/{datasetId}/etlImport

Call: client.datasets.etl_import_dataset(...) (async client: await a_client.datasets.etl_import_dataset(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
etl_dataset_vo ETLDatasetVO yes Data object
provider_id int \| None no None Provider id
replace_data bool \| None no None Replace Data
dataflow_id int yes Dataflow id

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset REPORTER WRITE, LEAD REPORTER
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

Note: replace_data is a real backend parameter (default false): when true the existing dataset data is replaced by the import. Confirmed in the production-line backend source; not live-tested (destructive).

Live-tested notes:

  • The ETL family is gated separately from the documented roles: a Bearer Custodian/Steward credential got 403 on the scratch dataset even though the docstring lists those roles, while an ApiKey worked for the exports. Do not assume a Bearer role level predicts ETL access; unverified per credential.

etl_import_dataset_dl

etlImportDatasetDL

HTTP: POST /dataset/{datasetId}/etlImportDL

Call: client.datasets.etl_import_dataset_dl(...) (async client: await a_client.datasets.etl_import_dataset_dl(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int yes
delimiter str yes
file_path_in_s3 str yes
provider_id int \| None no None
replace_data bool \| None no None
table_schema_id str \| None no None
preparation_code str \| None no None

Returns: dict[str, Any]

Allowed roles:

Not stated in the API spec.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • The ETL family is gated separately from the documented roles: a Bearer Custodian/Steward credential got 403 on the scratch dataset even though the docstring lists those roles, while an ApiKey worked for the exports. Do not assume a Bearer role level predicts ETL access; unverified per credential.

export_dataset_to_file

Export the whole dataset to dest, waiting for the file.

Call: client.datasets.export_dataset_to_file(...) (async client: await a_client.datasets.export_dataset_to_file(...))

Argument Type Required Default Description
dataset_id int yes
dataset_name str yes
dest str \| os.PathLike[str] yes
mime_type str no 'csv'
big_data bool no True
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: None

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

dataset_name is the dataset's name (the backend names the file after it). Raises JobError after timeout seconds without a file.

Not job-based: the backend starts generating the file in the background and tells only the Reportnet UI (a user notification); there is no job id or polling URL. fetch_export_file() / the *_to_file() helpers therefore poll the download until a non-empty body arrives. A file left from an earlier export with the same name can be served instead of the new one (the normal download deletes the file, the big_data one does not). Read from DatasetControllerImpl / FileTreatmentHelper (MasterDataLakes branch; develop has no big_data variants). Live (2026-10-23, Bearer only: the routes reject an ApiKey with 403) production behaves like the big_data (...DL) routes, which is what the Reportnet UI calls; the plain routes accepted a request but never produced a file. Hence big_data=True is the default; for the dataset export use zip csv (plain csv produced no file).

Live-tested notes:

  • Live-checked with mime_type='zip csv' (ZIP with one CSV per table); plain csv did not work.

export_dataset_with_job_to_file

Export a dataset (v3 job variant) into dest, waiting for the job.

Call: client.datasets.export_dataset_with_job_to_file(...) (async client: await a_client.datasets.export_dataset_with_job_to_file(...))

Argument Type Required Default Description
dataset_id int yes
dataflow_id int yes
dest str \| os.PathLike[str] yes
table_schema_id str \| None no None
provider_id int \| None no None
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: None

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

etl_export_dataset_with_job() (/dataset/v3/etlExport/{id}) only starts an async job. This polls its pollingUrl (/orchestrator/jobs/pollForJobStatus/{jobId}, answers {"status": ...}; QUEUED / IN_PROGRESS while it runs, see reportnet_api.jobs) every poll_interval seconds until FINISHED, then downloads the downloadUrl it returns (/orchestrator/jobs/downloadEtlExportedFile/{jobId}) to dest. Raises JobError (ExportJobError) on a failed/refused/cancelled job, on an error answer, or after timeout seconds. Same roles as etl_export_dataset_with_job(). progress=True shows one updating status line, a callable gets event dicts (see reportnet_api.jobs.progress_event).

Written from the MasterDataLakes branch of the Reportnet 3 backend repository (the job and the orchestrator's poll/download routes); untested live.

Live-tested notes:

  • Only the job start (v3) was tested live; the full flow is unverified.

export_table_to_file

Export one table to dest, waiting for the file: start the export, then poll the download.

Call: client.datasets.export_table_to_file(...) (async client: await a_client.datasets.export_table_to_file(...))

Argument Type Required Default Description
dataset_id int yes
table_name str yes
table_schema_id str yes
dest str \| os.PathLike[str] yes
mime_type str no 'csv'
level_error list[str] \| None no None
id_rules str \| None no None
field_value str \| None no None
big_data bool no True
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: None

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

table_name is the table's name (the backend names the file after it); table_schema_id selects the table; mime_type must be a bare extension (csv, xlsx). Raises JobError after timeout seconds without a file.

Not job-based: the backend starts generating the file in the background and tells only the Reportnet UI (a user notification); there is no job id or polling URL. fetch_export_file() / the *_to_file() helpers therefore poll the download until a non-empty body arrives. A file left from an earlier export with the same name can be served instead of the new one (the normal download deletes the file, the big_data one does not). Read from DatasetControllerImpl / FileTreatmentHelper (MasterDataLakes branch; develop has no big_data variants). Live (2026-10-23, Bearer only: the routes reject an ApiKey with 403) production behaves like the big_data (...DL) routes, which is what the Reportnet UI calls; the plain routes accepted a request but never produced a file. Hence big_data=True is the default; for the dataset export use zip csv (plain csv produced no file).

Live-tested notes:

  • Live-checked with a Bearer token on the scratch dataset: a CSV with all rows in 0.6s (big_data=True). Short-lived Bearer tokens can expire during a long poll.

export_zip_csv_to_file

Export a dataset as a ZIP of CSV files into dest, waiting for the job.

Call: client.datasets.export_zip_csv_to_file(...) (async client: await a_client.datasets.export_zip_csv_to_file(...))

Argument Type Required Default Description
dataset_id int yes
dataflow_id int yes
dest str \| os.PathLike[str] yes
table_schema_id str \| None no None
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: None

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

etl_export_zip_csv() (/dataset/v4/etlExport/{id}) only starts an async job. This polls its pollingUrl (/orchestrator/jobs/pollForJobStatus/{jobId}, answers {"status": ...}; QUEUED / IN_PROGRESS while it runs, see reportnet_api.jobs) every poll_interval seconds until FINISHED, then downloads the downloadUrl it returns (/orchestrator/jobs/downloadEtlExportedFile/{jobId}) to dest. Raises JobError (ExportJobError) on a failed/refused/cancelled job, on an error answer, or after timeout seconds. Same roles as etl_export_zip_csv(). progress=True shows one updating status line, a callable gets event dicts (see reportnet_api.jobs.progress_event).

Written from the MasterDataLakes branch of the Reportnet 3 backend repository (the job and the orchestrator's poll/download routes); untested live.

Live-tested notes:

  • Live-checked end to end with an ApiKey (Bearer got 403).

export_zip_parquet_to_file

Export a dataset as a ZIP of Parquet files into dest, waiting for the job.

Call: client.datasets.export_zip_parquet_to_file(...) (async client: await a_client.datasets.export_zip_parquet_to_file(...))

Argument Type Required Default Description
dataset_id int yes
dataflow_id int yes
dest str \| os.PathLike[str] yes
table_schema_id str \| None no None
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: None

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

etl_export_zip_parquet() (/dataset/v5/etlExport/{id}) only starts an async job. This polls its pollingUrl (/orchestrator/jobs/pollForJobStatus/{jobId}, answers {"status": ...}; QUEUED / IN_PROGRESS while it runs, see reportnet_api.jobs) every poll_interval seconds until FINISHED, then downloads the downloadUrl it returns (/orchestrator/jobs/downloadEtlExportedFile/{jobId}) to dest. Raises JobError (ExportJobError) on a failed/refused/cancelled job, on an error answer, or after timeout seconds. Same roles as etl_export_zip_parquet(). progress=True shows one updating status line, a callable gets event dicts (see reportnet_api.jobs.progress_event).

Written from the MasterDataLakes branch of the Reportnet 3 backend repository (the job and the orchestrator's poll/download routes); untested live.

Live-tested notes:

  • Live-checked end to end with an ApiKey.

fetch_export_file

(or downloadFileDL): download a generated export file.

HTTP: GET /dataset/{datasetId}/downloadFile

Call: client.datasets.fetch_export_file(...) (async client: await a_client.datasets.fetch_export_file(...))

Argument Type Required Default Description
dataset_id int yes
file_name str yes
dest str \| os.PathLike[str] yes
big_data bool no True

Returns: bool

Allowed roles:

Not stated in the API spec.

Saves to dest and returns True, or returns False without leaving a file when the backend answered with an empty body (file not generated yet or not found: the backend swallows that error).

Not job-based: the backend starts generating the file in the background and tells only the Reportnet UI (a user notification); there is no job id or polling URL. fetch_export_file() / the *_to_file() helpers therefore poll the download until a non-empty body arrives. A file left from an earlier export with the same name can be served instead of the new one (the normal download deletes the file, the big_data one does not). Read from DatasetControllerImpl / FileTreatmentHelper (MasterDataLakes branch; develop has no big_data variants). Live (2026-10-23, Bearer only: the routes reject an ApiKey with 403) production behaves like the big_data (...DL) routes, which is what the Reportnet UI calls; the plain routes accepted a request but never produced a file. Hence big_data=True is the default; for the dataset export use zip csv (plain csv produced no file).

Live-tested notes:

  • An unknown or not-yet-generated file gives an empty 200, so this returns False; the DL download does not delete the file, so a stale one can be served.

generate_import_presigned_url

generateImportPresignedUrl

HTTP: GET /dataset/{datasetId}/generateImportPresignedUrl

Call: client.datasets.generate_import_presigned_url(...) (async client: await a_client.datasets.generate_import_presigned_url(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
delimiter str \| None no None File delimiter
etl_import bool \| None no None Etl Import
file_name str \| None no None File name
integration_id int \| None no None Integration id
provider_id int \| None no None Provider id
replace bool \| None no None Replace current data
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
dataflow_id int yes Dataflow id

Returns: JobPresignedUrlInfo

Allowed roles:

Not stated in the API spec.

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • A GET that is not side-effect-free: every call allocates a server-side jobId and S3 object path, even if the URL is never used.

get_attachment

Download attachment by field id

HTTP: GET /dataset/v1/{datasetId}/field/{fieldId}/attachment

Call: client.datasets.get_attachment(...) (async client: await a_client.datasets.get_attachment(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
field_id str yes Field id
dest str \| os.PathLike[str] yes
field_name str \| None no None Field name
file_name str \| None no None File name
provider_code str \| None no None Provider code
provider_id int \| None no None Provider id
record_id str \| None no None Record id
table_schema_name str \| None no None Table schema name
dataflow_id int yes Dataflow id

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset CUSTODIAN, STEWARD, OBSERVER, REPORTER WRITE, REPORTER READ, LEAD REPORTER, STEWARD SUPPORT
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE, EDITOR READ
EU dataset CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
Data collection CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT

Live-tested notes:

  • The default Accept: application/json gets a 406 from this route (Spring content negotiation against the controller's produces); Accept: */* gets through. The generated method now sends a matching Accept itself (mocked tests only, not re-tested live).
  • Past the 406, the live test ended in a 500 (no real attachment data on the scratch dataset), so the success path is inconclusive.

get_available_for_manual_editing_tables

getAvailableForManualEditingTables

HTTP: GET /dataset/getAvailableForManualEditingTables/{datasetId}

Call: client.datasets.get_available_for_manual_editing_tables(...) (async client: await a_client.datasets.get_available_for_manual_editing_tables(...))

Argument Type Required Default Description
dataset_id int yes

Returns: list[TableSchemaIdNameVO]

Allowed roles:

Not stated in the API spec.

get_iceberg_tables

getIcebergTables

HTTP: GET /dataset/getIcebergTables

Call: client.datasets.get_iceberg_tables(...) (async client: await a_client.datasets.get_iceberg_tables(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int \| None no None
provider_id int \| None no None
preparation_code str \| None no None

Returns: list[DatasetTableVO]

Allowed roles:

Not stated in the API spec.

preparation_code (sent as preparationCode; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

getImportRelatedStatistics

HTTP: GET /dataset/getImportRelatedStatistics/{datasetId}

Call: client.datasets.get_import_related_statistics(...) (async client: await a_client.datasets.get_import_related_statistics(...))

Argument Type Required Default Description
dataset_id int yes

Returns: dict[str, Any]

Allowed roles:

Not stated in the API spec.

Live-tested notes:

  • numberOfRecordsImported looks like the rows of the last import, not a table total (it stayed 1 after a second one-row import); lastImportDate does change per import.

get_record_geometry

getRecordGeometry

HTTP: GET /dataset/v1/{datasetId}/record/{recordId}/geometry

Call: client.datasets.get_record_geometry(...) (async client: await a_client.datasets.get_record_geometry(...))

Argument Type Required Default Description
dataflow_id int yes
dataset_id int yes
field_id str yes
id_table_schema str yes
record_id str yes
download_file bool \| None no None
field_name str \| None no None
provider_id int \| None no None

Returns: str

Allowed roles:

Not stated in the API spec.

get_released_dataset_data_info

getReleasedDatasetDataInfo

HTTP: GET /dataset/getReleasedDatasetDataInfo

Call: client.datasets.get_released_dataset_data_info(...) (async client: await a_client.datasets.get_released_dataset_data_info(...))

Argument Type Required Default Description
collection_dataset_id int yes
provider_code str yes
table_schema_id str yes

Returns: ReleasedDatasetDataInfoVO

Allowed roles:

Not stated in the API spec.

import_big_file_data

Import file to dataset data (Large files)

HTTP: POST /dataset/v2/importFileData/{datasetId}

Call: client.datasets.import_big_file_data(...) (async client: await a_client.datasets.import_big_file_data(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
file str \| os.PathLike[str] yes File to upload
dataflow_id int \| None no None Dataflow id
delimiter str \| None no None File delimiter
fme_job_id str \| None no None Fme Job Id
integration_id int \| None no None Integration id
job_id int \| None no None Job Id
provider_id int \| None no None Provider id
replace bool \| None no None Replace current data
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None
timeout float \| httpx.Timeout \| None no None

Returns: dict[str, Any]

Allowed roles:

Dataset type Roles
Reporting dataset LEAD REPORTER, REPORTER WRITE, NATIONAL COORDINATOR
Data collection CUSTODIAN, STEWARD
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

Overrides the generated method. An empty response body returns {} (data lake datasets answer void: the import is done inside the request, MasterDataLakes DatasetControllerImpl:391-422; other datasets answer a job map), and timeout overrides the client's timeout for this call only (a lake import can run for minutes). preparation_code is sent as code.

Live-tested notes:

  • Job-based: returns {jobId, pollingUrl} and the import is not done yet; wait with wait_for_job or use import_file_and_wait. The uploaded file name must match a table name (e.g. TestTable.csv), otherwise the job is CANCELED with an info explaining it.
  • A second import to the same dataset while one is running gets 423 (LockedError); its body message says 'unknown error' but the cause is another job still QUEUED or IN_PROGRESS for the dataset (the RN3 UI says so). Wait for the first job before starting the next.

import_file_and_wait

Upload a file into a dataset and wait until the import is visible.

Call: client.datasets.import_file_and_wait(...) (async client: await a_client.datasets.import_file_and_wait(...))

Argument Type Required Default Description
dataset_id int yes
file str \| os.PathLike[str] yes
dataflow_id int \| None no None
delimiter str \| None no None
integration_id int \| None no None
provider_id int \| None no None
replace bool \| None no None
table_schema_id str \| None no None
big_file bool no True
confirm_statistics bool no True
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: dict[str, Any]

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

Reads get_import_related_statistics() as a baseline, uploads file with import_big_file_data() (big_file=True, the default; async job) or import_file_data() (big_file=False; returns nothing and merges in the background), then waits:

  • big file: polls the answer's pollingUrl until the job is FINISHED (wait_for_job()); if the answer has no pollingUrl this step is skipped. Once the job is FINISHED it is authoritative: statistics then get only a short grace period to show the change, after which the latest statistics are returned anyway (an empty or identical file may change nothing).
  • otherwise (small file, or no pollingUrl): polls get_import_related_statistics() until a table's (lastImportDate, numberOfRecordsImported) differs from the baseline (only table_schema_id's table when given), else raises on timeout. Pass confirm_statistics=False to trust the job alone (big file only; a missing pollingUrl then raises, though the upload was already sent).

check_import_process() is never used: its lock stayed set long after the data was in (live-tested). list_imported_files() is not used either: a file is listed before its data is merged. Returns the final statistics answer. Raises JobError on a failed/refused/cancelled job, or when timeout seconds pass while waiting (the upload may still complete afterwards; nothing is rolled back, so check before retrying). timeout bounds the waiting, not the baseline read or the upload itself, and poll_interval / timeout apply to both polling phases combined. Roles as for the underlying import method. progress=True shows one updating status line (a callable gets event dicts); its elapsed time counts from the start of the waiting.

Limits of the statistics check: without table_schema_id any table's change counts, so a concurrent import into the same dataset can be mistaken for yours; and a replace that makes a table drop out of the statistics is not seen as a change.

Verified live (2026-10-23, Bearer, scratch dataset): import_big_file_data returns a pollingUrl carrying datasetId/dataflowId, the job reached FINISHED in ~20s, and lastImportDate changed (the count stayed at 1: numberOfRecordsImported looks like the last import's rows, not a table total, so don't compare the count alone). The file name must match a table name or the job is CANCELED. The imported row was confirmed in the table via the v4 CSV export. An ApiKey import also worked (job FINISHED, statistics changed). NOT verified live: the big_file=False path with this helper.

Live-tested notes:

  • Live-checked with both Bearer and ApiKey (job FINISHED in ~20-25s). Not verified live: the big_file=False path and replace=True; on the small-file path an import that changes neither statistics value reads as a timeout.

import_file_data

Import file to dataset data (Large files not allowed > 50 MB)

HTTP: POST /dataset/v1/{datasetId}/importFileData

Call: client.datasets.import_file_data(...) (async client: await a_client.datasets.import_file_data(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
file str \| os.PathLike[str] yes File to upload
dataflow_id int \| None no None Dataflow id
delimiter str \| None no None File delimiter
fme_job_id str \| None no None Fme Job Id
integration_id int \| None no None Integration id
job_id int \| None no None Job Id
provider_id int \| None no None Provider id
replace bool \| None no None Replace current data
table_schema_id str \| None no None Table schema id
preparation_code str \| None no None

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset LEAD REPORTER, REPORTER WRITE, NATIONAL COORDINATOR
Data collection CUSTODIAN, STEWARD
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

preparation_code (sent as code; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

Live-tested notes:

  • Returns immediately with None; the import was confirmed to complete in the background. Check completion via get_import_related_statistics(), not check_import_process().

is_iceberg_table_created

isIcebergTableCreated

HTTP: GET /dataset/isIcebergTableCreated/{datasetId}/{tableSchemaId}

Call: client.datasets.is_iceberg_table_created(...) (async client: await a_client.datasets.is_iceberg_table_created(...))

Argument Type Required Default Description
dataset_id int yes
table_schema_id str yes
preparation_code str \| None no None

Returns: bool

Allowed roles:

Not stated in the API spec.

preparation_code (sent as preparationCode; not in the swagger snapshot, read from the backend source) selects a preparation dataset instead of the regular one.

list_imported_files

Returns all imported files for a given dataset

HTTP: GET /dataset/list-imported-files

Call: client.datasets.list_imported_files(...) (async client: await a_client.datasets.list_imported_files(...))

Argument Type Required Default Description
dataset_id int yes

Returns: list[ImportedFilesDirectoriesVO]

Allowed roles:

Not stated in the API spec.

Live-tested notes:

  • Needs Custodian/Steward: an ApiKey got 403, a Bearer Custodian/Steward credential returned [] on the scratch dataset.

restore_prefilled_tables

restorePrefilledTables

HTTP: POST /dataset/restorePrefilledTables/{datasetId}

Call: client.datasets.restore_prefilled_tables(...) (async client: await a_client.datasets.restore_prefilled_tables(...))

Argument Type Required Default Description
dataset_id int yes
table_schema_id str \| None no None

Returns: None

Allowed roles:

Not stated in the API spec.

start_dataset_export

(or exportDatasetFileDL): start exporting the whole dataset.

HTTP: GET /dataset/{datasetId}/exportDatasetFile

Call: client.datasets.start_dataset_export(...) (async client: await a_client.datasets.start_dataset_export(...))

Argument Type Required Default Description
dataset_id int yes
mime_type str no 'csv'
big_data bool no True

Returns: None

Allowed roles:

Not stated in the API spec.

mime_type is csv, xlsx, ... or zip csv / zip xlsx (a space; the backend splits it). The file is <dataset name>.zip for the zip types, else <dataset name>.<ext>. Returns nothing.

Not job-based: the backend starts generating the file in the background and tells only the Reportnet UI (a user notification); there is no job id or polling URL. fetch_export_file() / the *_to_file() helpers therefore poll the download until a non-empty body arrives. A file left from an earlier export with the same name can be served instead of the new one (the normal download deletes the file, the big_data one does not). Read from DatasetControllerImpl / FileTreatmentHelper (MasterDataLakes branch; develop has no big_data variants). Live (2026-10-23, Bearer only: the routes reject an ApiKey with 403) production behaves like the big_data (...DL) routes, which is what the Reportnet UI calls; the plain routes accepted a request but never produced a file. Hence big_data=True is the default; for the dataset export use zip csv (plain csv produced no file).

Live-tested notes:

  • Live: zip csv worked with big_data=True (file <dataset name>.zip); plain csv produced no file within 40s. Bearer only.

start_table_export

(or exportFileDL with big_data=True): start exporting one table.

HTTP: POST /dataset/exportFile

Call: client.datasets.start_table_export(...) (async client: await a_client.datasets.start_table_export(...))

Argument Type Required Default Description
dataset_id int yes
mime_type str no 'csv'
table_schema_id str \| None no None
level_error list[str] \| None no None
id_rules str \| None no None
field_value str \| None no None
big_data bool no True

Returns: None

Allowed roles:

Not stated in the API spec.

mime_type is the file extension (csv, xlsx, ...); without table_schema_id the whole dataset is exported under the dataset's name. Optional filters (ExportFilterVO): level_error (names of the backend's ErrorTypeEnum), id_rules, field_value; big_data=True also sends an empty qcCodes string. Returns nothing; the file is named <table name>.<mime_type>.

Not job-based: the backend starts generating the file in the background and tells only the Reportnet UI (a user notification); there is no job id or polling URL. fetch_export_file() / the *_to_file() helpers therefore poll the download until a non-empty body arrives. A file left from an earlier export with the same name can be served instead of the new one (the normal download deletes the file, the big_data one does not). Read from DatasetControllerImpl / FileTreatmentHelper (MasterDataLakes branch; develop has no big_data variants). Live (2026-10-23, Bearer only: the routes reject an ApiKey with 403) production behaves like the big_data (...DL) routes, which is what the Reportnet UI calls; the plain routes accepted a request but never produced a file. Hence big_data=True is the default; for the dataset export use zip csv (plain csv produced no file).

Live-tested notes:

  • Needs a Bearer token (an ApiKey gets 403). Live: with the default big_data=True (the exportFileDL route the Reportnet UI calls) the export worked; the plain route was accepted but never produced a file. Filters and non-csv formats are unverified.

update_attachment

Update attachment by field id

HTTP: PUT /dataset/v1/{datasetId}/field/{fieldId}/attachment

Call: client.datasets.update_attachment(...) (async client: await a_client.datasets.update_attachment(...))

Argument Type Required Default Description
dataset_id int yes Dataset id
field_id str yes Field id
file str \| os.PathLike[str] yes
dataflow_id int \| None no None Dataflow id
field_name str \| None no None Field name
previous_file_name str \| None no None Previous File Name
provider_id int \| None no None Provider id
record_id str \| None no None Record id
table_schema_name str \| None no None Table schema name

Returns: None

Allowed roles:

Dataset type Roles
Reporting dataset LEAD REPORTER, REPORTER WRITE, NATIONAL COORDINATOR
Data collection CUSTODIAN, STEWARD
Test dataset CUSTODIAN, STEWARD, STEWARD SUPPORT
Reference dataset CUSTODIAN, STEWARD
Design dataset CUSTODIAN, STEWARD, EDITOR WRITE
EU dataset CUSTODIAN, STEWARD

update_dataset_name

rename a dataset (as the web app renames a design dataset, i.e. its schema).

HTTP: PUT /datasetmetabase/updateDatasetName

Call: client.datasets.update_dataset_name(...) (async client: await a_client.datasets.update_dataset_name(...))

Argument Type Required Default Description
dataset_id int yes
name str yes

Returns: None

Allowed roles:

Not stated in the API spec.

DatasetMetabaseControllerImpl#updateDatasetName (hidden). Requires DATASCHEMA_STEWARD, DATASCHEMA_CUSTODIAN or DATASCHEMA_EDITOR_WRITE on the dataset. The backend trims name and answers 400 unless it matches [a-zA-Z0-9\s()_-]+, or for an unknown dataset. It does not check that the name is unique in the dataflow.

update_geometry

updateGeometry

HTTP: PUT /dataset/{datasetId}/updateGeometry

Call: client.datasets.update_geometry(...) (async client: await a_client.datasets.update_geometry(...))

Argument Type Required Default Description
dataset_id int yes

Returns: None

Allowed roles:

Not stated in the API spec.

update_geometry_v2

updateGeometryV2

HTTP: PUT /dataset/v2/{datasetId}/updateGeometry

Call: client.datasets.update_geometry_v2(...) (async client: await a_client.datasets.update_geometry_v2(...))

Argument Type Required Default Description
dataset_id int yes

Returns: None

Allowed roles:

Not stated in the API spec.

wait_for_job

Wait for an async job to finish and return its last status answer.

Call: client.datasets.wait_for_job(...) (async client: await a_client.datasets.wait_for_job(...))

Argument Type Required Default Description
job dict[str, Any] \| str yes
poll_interval float no 2.0
timeout float no 300.0
progress Progress no None

Returns: dict[str, Any]

Allowed roles:

Not an endpoint of its own; the rights are those of the underlying calls.

Pass what import_big_file_data() (or any job-starting method) returned, or its pollingUrl. Polls every poll_interval seconds; raises JobError on a failed/refused/cancelled job or after timeout seconds. For an import, FINISHED is the job's own completion; check_import_process() is not a reliable signal (live-tested). progress=True shows one updating status line, a callable gets event dicts (reportnet_api.jobs.progress_event). Untested live.

Live-tested notes:

  • Waits for an Orchestrator job (e.g. from import_big_file_data or the etl_export v3/v4/v5 starters) to reach FINISHED; raises JobError otherwise.