Struct DuckLakeAdapter 

pub struct DuckLakeAdapter {
    pub lake_root: String,
}

Adapter rooted at a TRE Lake location.

Fields

lake_root: String

Implementations

impl DuckLakeAdapter

pub fn validate_object_storage_inputs<'a>( config: &ObjectLakeSessionConfig, storage_authentication: ObjectStorageAuthentication<'a>, ambient_environment_names: impl IntoIterator<Item = impl AsRef<str>>, ) -> Result<(), LakeError>

Validates object-storage provider and ambient-authority inputs without rendering Secret-bearing SQL.

pub fn open_existing_object_storage_catalog( config: &ObjectLakeSessionConfig, catalog_credential: &SecretMaterial, storage_authentication: ObjectStorageAuthentication<'_>, scratch: &ScratchAttempt, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Opens an existing object-backed Lake with explicit catalog and storage credentials and a private trusted-scratch attempt.

pub fn open_existing_object_storage_catalog_observed( context: Option<&CorrelationContext>, config: &ObjectLakeSessionConfig, catalog_credential: &SecretMaterial, storage_authentication: ObjectStorageAuthentication<'_>, scratch: &ScratchAttempt, observations: &mut LakeCatalogObservations, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Observes the existing attach; it never probes or retries independently.

pub fn initialize_object_storage_catalog( config: &ObjectLakeSessionConfig, catalog_credential: &SecretMaterial, storage_authentication: ObjectStorageAuthentication<'_>, scratch: &ScratchAttempt, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Initializes a new object-backed Lake after proving its configured prefix is empty.

pub fn build_filesystem_attach_plan( config: &FilesystemLakeSessionConfig, credential: &SecretMaterial, ) -> Result<DuckLakeAttachPlan, LakeError>

Builds an existing-catalog attach plan from explicit filesystem and credential inputs. Lake location composition remains inside this adapter.

pub fn open_existing_filesystem_catalog( config: &FilesystemLakeSessionConfig, credential: &SecretMaterial, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Opens an existing filesystem Lake from explicit, non-ambient inputs.

pub fn open_existing_filesystem_catalog_with_scratch( config: &FilesystemLakeSessionConfig, credential: &SecretMaterial, scratch: &ScratchAttempt, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Opens an existing filesystem Lake while directing all DuckDB temporary work into one private trusted-scratch attempt rather than the Lake.

pub fn open_existing_filesystem_catalog_observed( context: Option<&CorrelationContext>, config: &FilesystemLakeSessionConfig, credential: &SecretMaterial, scratch: &ScratchAttempt, observations: &mut LakeCatalogObservations, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Records the time authenticated catalog evidence was actually obtained.

pub fn initialize_filesystem_catalog_with_scratch( config: &FilesystemLakeSessionConfig, credential: &SecretMaterial, scratch: &ScratchAttempt, ) -> Result<DuckLakeOpenedCatalog, LakeError>

Initializes a new filesystem Lake in a previously absent namespace.

pub fn new(lake_root: impl Into<String>) -> Self

Creates an adapter for the supplied lake root.

pub fn local_layout(&self) -> Result<DuckLakeLocalLayout, LakeError>

Returns the deterministic local layout below the lake root.

Errors

Returns LakeError::EmptyLakeRoot if the configured root is blank.

pub fn health_check_observed( &self, connection: &Connection, observations: &mut LakeCatalogObservations, ) -> Result<DuckLakeHealth, LakeError>

Observe an explicitly authorized health read on the retained connection.

pub fn health_check( &self, connection: &Connection, ) -> Result<DuckLakeHealth, LakeError>

Reads DuckLake settings and lightweight catalog counts.

Errors

Returns an error if DuckDB metadata queries fail or DuckLake reports an unexpected encryption setting.

impl DuckLakeAdapter

pub fn validate_dataset_file( &self, connection: &Connection, source_path: &Path, format: DatasetFileFormat, options: &DatasetFileReadOptions, ) -> Result<(), LakeError>

Validates a dataset file by scanning it with the same DuckDB reader used by governed dataset imports, without creating a persistent relation.

Errors

Returns an error if the source file is missing or DuckDB cannot parse and scan the complete file with the requested format and options.

pub fn replace_server_managed_dataset_tables_from_csv( &self, opened: &DuckLakeOpenedCatalog, scratch: &ScratchAttempt, study_id: StudyId, seeds: &[DatasetCsvSeed<'_>], authority: &mut dyn DatasetMaintenanceAuthority, ) -> Result<Vec<LoadedDatasetTable>, LakeError>

Atomically replaces the exact Study dataset set in an existing server-managed DuckLake catalog from trusted CSV inputs.

Errors

Returns an error unless the catalog was opened as an existing server-managed catalog without an encryption override, or if private staging, dataset replacement, or exact-set verification fails.

pub fn load_dataset_table_from_file_reserved( &self, connection: &Connection, authority: &mut dyn DatasetWriteAuthority, request: &LoadDatasetTableFromFileRequest, ) -> Result<LoadedDatasetTable, LakeError>

Loads only the exact output held by an active shared reservation.

pub fn load_dataset_table_from_file_reserved_observed( &self, context: Option<CorrelationContext>, connection: &Connection, authority: &mut dyn DatasetWriteAuthority, request: &LoadDatasetTableFromFileRequest, ) -> Result<LoadedDatasetTable, LakeError>

Observes one reserved load, including its existing rollback outcome.

pub fn load_restricted_query_output_reserved( &self, connection: &Connection, authority: &mut dyn DatasetWriteAuthority, target: &LoadDatasetTableFromSqlRequest, output: PreparedQueryOutput, ) -> Result<LoadedDatasetTable, LakeError>

The output file is produced by the restricted executor, never supplied as a client path or SQL document. Existing reservation/cleanup semantics remain the sole authority for publishing its Dataset table.

pub fn load_dataset_table_from_sql_reserved( &self, connection: &Connection, authority: &mut dyn DatasetWriteAuthority, request: &LoadDatasetTableFromSqlRequest, ) -> Result<LoadedDatasetTable, LakeError>

Loads only the exact output held by an active shared reservation.

pub fn load_redcap_form_dataset_reserved( &self, connection: &Connection, authority: &mut dyn DatasetWriteAuthority, request: &LoadRedcapFormDatasetRequest, ) -> Result<LoadedDatasetTable, LakeError>

Loads only the exact output held by an active shared reservation.

pub fn cleanup_reserved_dataset_output( &self, connection: &Connection, authority: &mut dyn DatasetOutputAuthority, ) -> Result<(), LakeError>

Compensates only a still-owned, non-admitted output of a known attempt.

pub fn drop_dataset_table( &self, connection: &Connection, relation: &DatasetTableRelation, ) -> Result<(), LakeError>

Drops a dataset table if it exists.

Errors

Returns an error if DuckDB rejects the DROP TABLE command.

pub fn export_dataset_table( &self, connection: &Connection, request: &ExportDatasetTableRequest, ) -> Result<ExportedDatasetTable, LakeError>

Exports a versioned dataset table to CSV, NDJSON, Parquet, or Arrow IPC.

Errors

Returns an error if the relation cannot be read, the destination directory cannot be created, DuckDB export fails, or the Arrow/Parquet writer fails.

pub fn preview_dataset_table( &self, connection: &Connection, request: &PreviewDatasetTableRequest, ) -> Result<PreviewedDatasetTable, LakeError>

Reads a bounded, stringified row preview for a versioned dataset table.

Errors

Returns an error if the relation cannot be inspected or queried.

impl DuckLakeAdapter

pub fn restore_dataset_source( &self, scratch: &ScratchAttempt, datafile: &DataFileRecord, format: DatasetFileFormat, ) -> Result<PreparedDatasetSource, LakeError>

Restores a managed Datafile using only the configured scratch capability. Failed restoration removes the source and all partial intermediate files.

pub fn restore_dataset_source_observed( &self, context: Option<CorrelationContext>, scratch: &ScratchAttempt, datafile: &DataFileRecord, format: DatasetFileFormat, ) -> Result<PreparedDatasetSource, LakeError>

Observes the existing storage read without formatting content or paths.

pub fn stage_dataset_source_file( &self, scratch: &ScratchAttempt, source: &Path, format: DatasetFileFormat, ) -> Result<PreparedDatasetSource, LakeError>

Stages an external source whose reader needs writable conversion scratch.

impl DuckLakeAdapter

pub fn stage_datafile_content<R: Read + ?Sized>( &self, scratch_attempt: &ScratchAttempt, request: &StageDataFileStreamRequest, validation: Option<(DatasetFileFormat, DatasetFileReadOptions)>, source: &mut R, ) -> Result<StagedDataFile, LakeError>

Validates and stages caller-provided content without exposing a scratch path.

Errors

Returns an error if scratch staging, optional DuckDB validation, managed payload staging, or scratch cleanup fails.

pub fn stage_datafile_content_validated<R: Read + ?Sized>( &self, scratch_attempt: &ScratchAttempt, request: &StageDataFileStreamRequest, validation: Option<(DatasetFileFormat, DatasetFileReadOptions)>, upload: Option<&UploadValidation>, source: &mut R, ) -> Result<StagedDataFile, LakeError>

pub fn stage_datafile( &self, request: &StageDataFileRequest, ) -> Result<StagedDataFile, LakeError>

Stages a local source file into the study lake area.

Errors

Returns an error if the EDAM format is empty, the source filename is invalid, the destination already exists, filesystem access fails, or compression/encryption fails.

pub fn stage_datafile_stream<R: Read + ?Sized>( &self, request: &StageDataFileStreamRequest, source: &mut R, ) -> Result<StagedDataFile, LakeError>

Stages bytes from a reader into the study lake area.

Errors

Returns an error if the EDAM format is empty, the supplied source filename contains path separators, the destination already exists, filesystem access fails, or compression/encryption fails.

pub fn delete_datafile( &self, request: &DeleteDataFileRequest, ) -> Result<DeletedDataFile, LakeError>

Removes a managed stored data file from the lake.

The storage URI is resolved through the same lake-root checks used for materialization/export, so callers never handle Restricted local references.

pub fn materialize_datafile( &self, request: &MaterializeDataFileRequest, ) -> Result<MaterializedDataFile, LakeError>

Restores a stored data file to its logical bytes.

Errors

Returns an error if the storage URI is invalid for the lake layout, the digest does not match metadata, required compression/encryption metadata is missing or unsupported, or filesystem/cryptographic operations fail.

pub fn export_datafile( &self, request: &ExportDataFileRequest, ) -> Result<ExportedDataFile, LakeError>

Exports a stored data file, optionally writing a compressed copy.

Errors

Returns an error if materialization fails, the destination cannot be created, or the optional compression step fails.

Trait Implementations

impl Clone for DuckLakeAdapter

fn clone(&self) -> DuckLakeAdapter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DuckLakeAdapter

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.