Package {fabricQueryR}

Work with Microsoft Fabric from R

Description

'fabricQueryR' helps you find and work with Microsoft Fabric data from R. Start by discovering the workspaces and items available to you. Discovery returns read-only R6 objects that include the service fields and expose methods matched to each actionable resource. In most workflows, you can continue with $ methods without copying IDs, endpoints, or credentials by hand. The same operations can also be called through the corresponding ⁠fabric_*()⁠ functions

Where to start

• Use fabric_workspaces() and the typed discovery helpers, such as fabric_lakehouses() or fabric_semantic_models(), to find data. A workspace can also continue discovery with ⁠$lakehouses()⁠ (fabric_lakehouses()) and ⁠$semantic_models()⁠ (fabric_semantic_models()); see FabricItem

• Use fabric_sql_tables() to discover tables and views across Warehouse, SQL Database, Warehouse snapshot, or Lakehouse SQL endpoints, then use ⁠$sql_read_table()⁠ (fabric_sql_read_table()) or ⁠$sql_query()⁠ (fabric_sql_query()) to read them

• Use ⁠$dax_query()⁠ (fabric_pbi_dax_query()) on a semantic model

• Use ⁠$livy_query()⁠ (fabric_livy_query()), ⁠$livy_session()⁠ (fabric_livy_session()), or ⁠$livy_batch_submit()⁠ (fabric_livy_batch_submit()) on a Lakehouse for Spark processing

• Use fabric_lakehouse_schemas() and fabric_lakehouse_tables() to discover managed Delta tables; Lakehouse methods include ⁠$tables()⁠ (fabric_lakehouse_tables()), ⁠$read_table()⁠ (fabric_lakehouse_read_table()), ⁠$write_table()⁠ (fabric_lakehouse_write_table()), and ⁠$load_table()⁠ (fabric_lakehouse_load_table())

• Use fabric_onelake_files for ordinary files

• Use fabric_warehouse_schemas() and fabric_warehouse_tables() to discover Warehouse tables, then ⁠$read_table()⁠ (fabric_warehouse_read_table()) or ⁠$write_table()⁠ (fabric_warehouse_write_table()) on the Warehouse object

• Use fabric_mirrored_databases() and fabric_mirrored_database_tables() to discover and read continuously replicated Delta tables

• On an Eventhouse or KQL database, use ⁠$tables()⁠ (fabric_kql_tables()), ⁠$query()⁠ (fabric_kql_query()), ⁠$read_table()⁠ (fabric_kql_read_table()), ⁠$ingest()⁠ (fabric_kql_ingest()), ⁠$write_table()⁠ (fabric_kql_write_table()), and ⁠$export()⁠ (fabric_kql_export())

• On an API for GraphQL item, use ⁠$query()⁠ (fabric_graphql_query()), ⁠$schema()⁠ (fabric_graphql_schema()), and ⁠$paginate()⁠ (fabric_graphql_paginate())

• Use experimental fabric_function_invoke() to call published business logic through a User Data Function's explicit public URL

• On a runnable item, use ⁠$run()⁠ (fabric_job_run()), ⁠$status()⁠ (fabric_job_status()), ⁠$wait()⁠ (fabric_job_wait()), and ⁠$cancel()⁠ (fabric_job_cancel())

• See vignette("authentication", package = "fabricQueryR") for interactive and unattended authentication setup, required token audiences, and Fabric permissions

Author(s)

Maintainer: Luka Koning koningluka@gmail.com [copyright holder]

Authors:

• Luka Koning koningluka@gmail.com [copyright holder]

Other contributors:

• Kennispunt Twente info@kennispunttwente.nl [funder]

References

What is Microsoft Fabric?

Microsoft Fabric REST API documentation

See Also

Useful links:

• https://github.com/kennispunttwente/fabricQueryR

• https://kennispunttwente.github.io/fabricQueryR/

• Report bugs at https://github.com/kennispunttwente/fabricQueryR/issues

R6 objects for discovered Microsoft Fabric resources

Description

These generators back the default output = "r6" discovery interface. Users normally receive objects from fabric_workspaces(), fabric_items(), fabric_item(), the typed discovery helpers, or fabric_catalog_search() rather than constructing them directly.

Format

An R6::R6Class generator.

Details

Every object includes the complete Fabric API record. Read non-conflicting fields directly with $; use ⁠$get()⁠ for collision-safe field access and ⁠$as_list()⁠ or as.list() for a plain record. ⁠$get()⁠ is an object-only field helper. Record fields are read-only.

Methods delegate to the corresponding ⁠fabric_*()⁠ function. Their ... arguments are forwarded unchanged, and the credential used for discovery is reused while the object is in the current R process. An explicitly supplied token, tenant_id, client_id, auth_args, or api_base takes precedence. Job and refresh lifecycle methods prefer the supplied handle's in-process credential over the discovery credential. Bare IDs and handles whose credentials were removed by serialization use the discovery credential. The Fabric API base used for discovery is also reused, so chained methods stay on the same public, sovereign-cloud, or workspace endpoint.

SQL-capable resources inherit common ⁠sql_*()⁠ methods. Lakehouses, Warehouses, mirrored databases, Eventhouses, KQL databases, GraphQL APIs, semantic models, and runnable job items add workload-specific methods. Other discovered types are returned as FabricItem objects with ⁠$details()⁠ (fabric_item()) and record access. They do not expose methods that cannot operate from discovery metadata. This generic fallback also applies to typed Environment and User Data Function discovery; a typed helper and workload detail route do not by themselves imply a specialized R6 class.

FabricEventhouse and FabricKqlDatabase share the KQL methods documented below under their internal FabricKqlItem superclass: ⁠$query()⁠, ⁠$tables()⁠, ⁠$read_table()⁠, ⁠$ingest()⁠, ⁠$write_table()⁠, ⁠$export()⁠, ⁠$ingestion_status()⁠, and ⁠$ingestion_wait()⁠.

Value

The corresponding R6 generator.

Super class

FabricRecord -> FabricWorkspace

Methods

Public methods

• FabricWorkspace$new()

• FabricWorkspace$items()

• FabricWorkspace$item()

• FabricWorkspace$lakehouses()

• FabricWorkspace$warehouses()

• FabricWorkspace$warehouse_snapshots()

• FabricWorkspace$mirrored_databases()

• FabricWorkspace$sql_databases()

• FabricWorkspace$semantic_models()

• FabricWorkspace$eventhouses()

• FabricWorkspace$kql_databases()

• FabricWorkspace$notebooks()

• FabricWorkspace$data_pipelines()

• FabricWorkspace$spark_job_definitions()

• FabricWorkspace$environments()

• FabricWorkspace$user_data_functions()

• FabricWorkspace$graphql_apis()

• FabricWorkspace$shortcut_cache_reset()

FabricWorkspace$new()

Internal constructor used by discovery factories.

Usage

FabricWorkspace$new(
  record,
  legacy_class = c("fabric_workspace", "list"),
  credential = NULL,
  api_base = NULL
)

Arguments

FabricWorkspace$items()

Discover items in this workspace.

Usage

FabricWorkspace$items(...)

Arguments

Returns

A list of FabricItem objects or type-specific subclasses.

FabricWorkspace$item()

Discover and enrich one item in this workspace.

Usage

FabricWorkspace$item(item, ...)

Arguments

Returns

A FabricItem object or one of its subclasses.

FabricWorkspace$lakehouses()

Discover Lakehouses in this workspace.

Usage

FabricWorkspace$lakehouses(detail = TRUE, ...)

Arguments

Returns

A list of FabricLakehouse objects.

FabricWorkspace$warehouses()

Discover Warehouses in this workspace.

Usage

FabricWorkspace$warehouses(detail = TRUE, ...)

Arguments

Returns

A list of FabricWarehouse objects.

FabricWorkspace$warehouse_snapshots()

Discover Warehouse snapshots in this workspace.

Usage

FabricWorkspace$warehouse_snapshots(detail = TRUE, ...)

Arguments

Returns

A list of FabricWarehouseSnapshot objects.

FabricWorkspace$mirrored_databases()

Discover mirrored databases in this workspace.

Usage

FabricWorkspace$mirrored_databases(detail = TRUE, ...)

Arguments

Returns

A list of FabricMirroredDatabase objects.

FabricWorkspace$sql_databases()

Discover SQL databases in this workspace.

Usage

FabricWorkspace$sql_databases(detail = TRUE, ...)

Arguments

Returns

A list of FabricSqlDatabase objects.

FabricWorkspace$semantic_models()

Discover semantic models in this workspace.

Usage

FabricWorkspace$semantic_models(detail = FALSE, ...)

Arguments

Returns

A list of FabricSemanticModel objects.

FabricWorkspace$eventhouses()

Discover Eventhouses in this workspace.

Usage

FabricWorkspace$eventhouses(detail = TRUE, ...)

Arguments

Returns

A list of FabricEventhouse objects.

FabricWorkspace$kql_databases()

Discover KQL databases in this workspace.

Usage

FabricWorkspace$kql_databases(detail = TRUE, ...)

Arguments

Returns

A list of FabricKqlDatabase objects.

FabricWorkspace$notebooks()

Discover notebooks in this workspace.

Usage

FabricWorkspace$notebooks(detail = TRUE, ...)

Arguments

Returns

A list of FabricJobItem objects.

FabricWorkspace$data_pipelines()

Discover data pipelines in this workspace.

Usage

FabricWorkspace$data_pipelines(detail = TRUE, ...)

Arguments

Returns

A list of FabricJobItem objects.

FabricWorkspace$spark_job_definitions()

Discover Spark job definitions in this workspace.

Usage

FabricWorkspace$spark_job_definitions(detail = TRUE, ...)

Arguments

Returns

A list of FabricJobItem objects.

FabricWorkspace$environments()

Discover environments in this workspace.

Usage

FabricWorkspace$environments(detail = TRUE, ...)

Arguments

Returns

A list of FabricItem objects.

FabricWorkspace$user_data_functions()

Discover User Data Functions in this workspace. The service-principal development sandbox can use Core discovery, but it cannot provision and fully inspect disposable User Data Function fixtures.

Usage

FabricWorkspace$user_data_functions(detail = FALSE, ...)

Arguments

Returns

A list of FabricItem objects.

FabricWorkspace$graphql_apis()

Discover GraphQL APIs in this workspace.

Usage

FabricWorkspace$graphql_apis(detail = FALSE, ...)

Arguments

Returns

A list of FabricGraphQLApi objects.

FabricWorkspace$shortcut_cache_reset()

Reset this workspace's OneLake shortcut cache.

Usage

FabricWorkspace$shortcut_cache_reset(...)

Arguments

Returns

A fabric_operation handle.

Super class

FabricRecord -> FabricItem

Methods

Public methods

• FabricItem$new()

• FabricItem$details()

FabricItem$new()

Internal constructor used by discovery factories.

Usage

FabricItem$new(
  record,
  legacy_class = c("fabric_item", "list"),
  credential = NULL,
  api_base = NULL
)

Arguments

FabricItem$details()

Retrieve a fresh item record and supported workload details. User Data Function workload details require detail = TRUE and a delegated user identity.

Usage

FabricItem$details(...)

Arguments

Returns

A new FabricItem object or one of its subclasses.

Super classes

FabricRecord -> FabricItem -> FabricSqlItem -> FabricLakehouse

Methods

Public methods

• FabricLakehouse$schemas()

• FabricLakehouse$table()

• FabricLakehouse$tables()

• FabricLakehouse$read_table()

• FabricLakehouse$read_delta_table()

• FabricLakehouse$load_table()

• FabricLakehouse$write_table()

• FabricLakehouse$livy_query()

• FabricLakehouse$livy_session()

• FabricLakehouse$livy_batch_submit()

• FabricLakehouse$onelake_list()

• FabricLakehouse$onelake_metadata()

• FabricLakehouse$onelake_read_file()

• FabricLakehouse$onelake_write_file()

• FabricLakehouse$onelake_download()

• FabricLakehouse$onelake_upload()

• FabricLakehouse$onelake_delete()

• FabricLakehouse$schema_exists()

• FabricLakehouse$table_exists()

• FabricLakehouse$shortcuts()

• FabricLakehouse$shortcut()

• FabricLakehouse$shortcut_create()

• FabricLakehouse$shortcuts_bulk_create()

• FabricLakehouse$shortcut_delete()

FabricLakehouse$schemas()

List Lakehouse schemas.

Usage

FabricLakehouse$schemas(...)

Arguments

Returns

A schema inventory tibble.

FabricLakehouse$table()

Retrieve one Lakehouse table's metadata.

Usage

FabricLakehouse$table(table, ...)

Arguments

Returns

A one-row table metadata tibble.

FabricLakehouse$tables()

List Lakehouse tables.

Usage

FabricLakehouse$tables(...)

Arguments

Returns

A table inventory tibble.

FabricLakehouse$read_table()

Read one managed Delta table.

Usage

FabricLakehouse$read_table(table, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricLakehouse$read_delta_table()

Read a Delta table directly from OneLake.

Usage

FabricLakehouse$read_delta_table(table_path, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricLakehouse$load_table()

Load an existing file into a managed table.

Usage

FabricLakehouse$load_table(table, path, ...)

Arguments

Returns

A fabric_operation or completed operation result.

FabricLakehouse$write_table()

Write R or Arrow data to a managed table.

Usage

FabricLakehouse$write_table(table, data, ...)

Arguments

Returns

A completed write result.

FabricLakehouse$livy_query()

Run one Spark statement through Livy.

Usage

FabricLakehouse$livy_query(code, ...)

Arguments

Returns

A Livy statement result.

FabricLakehouse$livy_session()

Create a reusable Livy session.

Usage

FabricLakehouse$livy_session(...)

Arguments

Returns

A FabricLivySession.

FabricLakehouse$livy_batch_submit()

Submit a standalone Livy batch.

Usage

FabricLakehouse$livy_batch_submit(file, ...)

Arguments

Returns

A FabricLivyBatch or its result.

FabricLakehouse$onelake_list()

List OneLake files and directories.

Usage

FabricLakehouse$onelake_list(path = "", ...)

Arguments

Returns

A file inventory tibble.

FabricLakehouse$onelake_metadata()

Retrieve OneLake path metadata.

Usage

FabricLakehouse$onelake_metadata(path = "", ...)

Arguments

Returns

A one-row metadata tibble.

FabricLakehouse$onelake_read_file()

Read a supported file from OneLake.

Usage

FabricLakehouse$onelake_read_file(path, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricLakehouse$onelake_write_file()

Write data to a supported OneLake file.

Usage

FabricLakehouse$onelake_write_file(path, data, ...)

Arguments

Returns

A file-write result.

FabricLakehouse$onelake_download()

Download one OneLake file.

Usage

FabricLakehouse$onelake_download(path, ...)

Arguments

Returns

The local destination path.

FabricLakehouse$onelake_upload()

Upload a local file or raw vector to OneLake.

Usage

FabricLakehouse$onelake_upload(path, source, ...)

Arguments

Returns

A file-write result.

FabricLakehouse$onelake_delete()

Delete a OneLake path.

Usage

FabricLakehouse$onelake_delete(path, ...)

Arguments

Returns

TRUE, invisibly, after deletion.

FabricLakehouse$schema_exists()

Check whether a schema exists.

Usage

FabricLakehouse$schema_exists(schema, ...)

Arguments

Returns

One logical value.

FabricLakehouse$table_exists()

Check whether a table exists.

Usage

FabricLakehouse$table_exists(table, ...)

Arguments

Returns

One logical value.

FabricLakehouse$shortcuts()

List OneLake shortcuts.

Usage

FabricLakehouse$shortcuts(...)

Arguments

Returns

A shortcut inventory tibble.

FabricLakehouse$shortcut()

Retrieve one OneLake shortcut.

Usage

FabricLakehouse$shortcut(path, name, ...)

Arguments

Returns

A one-row shortcut tibble.

FabricLakehouse$shortcut_create()

Create a OneLake shortcut.

Usage

FabricLakehouse$shortcut_create(path, name, target, ...)

Arguments

Returns

A one-row shortcut tibble.

FabricLakehouse$shortcuts_bulk_create()

Create multiple OneLake shortcuts.

Usage

FabricLakehouse$shortcuts_bulk_create(shortcuts, ...)

Arguments

Returns

A fabric_operation handle.

FabricLakehouse$shortcut_delete()

Delete one OneLake shortcut.

Usage

FabricLakehouse$shortcut_delete(path, name, ...)

Arguments

Returns

TRUE, invisibly, after deletion.

Super classes

FabricRecord -> FabricItem -> FabricSqlItem -> FabricWarehouse

Methods

Public methods

• FabricWarehouse$schemas()

• FabricWarehouse$table()

• FabricWarehouse$tables()

• FabricWarehouse$read_table()

• FabricWarehouse$write_table()

• FabricWarehouse$read_delta_table()

FabricWarehouse$schemas()

List Warehouse schemas.

Usage

FabricWarehouse$schemas(...)

Arguments

Returns

A schema inventory tibble.

FabricWarehouse$table()

Retrieve one Warehouse table's metadata.

Usage

FabricWarehouse$table(table, ...)

Arguments

Returns

A one-row table metadata tibble.

FabricWarehouse$tables()

List Warehouse tables.

Usage

FabricWarehouse$tables(...)

Arguments

Returns

A table inventory tibble.

FabricWarehouse$read_table()

Read one Warehouse table.

Usage

FabricWarehouse$read_table(table, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricWarehouse$write_table()

Write R or Arrow data to a Warehouse table.

Usage

FabricWarehouse$write_table(table, data, staging_lakehouse, ...)

Arguments

Returns

A completed write result.

FabricWarehouse$read_delta_table()

Read a Delta table directly from OneLake.

Usage

FabricWarehouse$read_delta_table(table_path, ...)

Arguments

Returns

A tibble or Arrow stream.

Super classes

FabricRecord -> FabricItem -> FabricSqlItem -> FabricWarehouseSnapshot

Super classes

FabricRecord -> FabricItem -> FabricSqlItem -> FabricSqlDatabase

Super classes

FabricRecord -> FabricItem -> FabricSqlItem -> FabricMirroredDatabase

Methods

Public methods

• FabricMirroredDatabase$schemas()

• FabricMirroredDatabase$table()

• FabricMirroredDatabase$tables()

• FabricMirroredDatabase$read_table()

• FabricMirroredDatabase$read_delta_table()

FabricMirroredDatabase$schemas()

List mirrored database schemas.

Usage

FabricMirroredDatabase$schemas(...)

Arguments

Returns

A schema inventory tibble.

FabricMirroredDatabase$table()

Retrieve one mirrored table's metadata.

Usage

FabricMirroredDatabase$table(table, ...)

Arguments

Returns

A one-row table metadata tibble.

FabricMirroredDatabase$tables()

List mirrored database tables.

Usage

FabricMirroredDatabase$tables(...)

Arguments

Returns

A table inventory tibble.

FabricMirroredDatabase$read_table()

Read one mirrored Delta table.

Usage

FabricMirroredDatabase$read_table(table, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricMirroredDatabase$read_delta_table()

Read a Delta table directly from OneLake.

Usage

FabricMirroredDatabase$read_delta_table(table_path, ...)

Arguments

Returns

A tibble or Arrow stream.

Super classes

FabricRecord -> FabricItem -> FabricKqlItem

Methods

Public methods

• FabricKqlItem$query()

• FabricKqlItem$tables()

• FabricKqlItem$read_table()

• FabricKqlItem$ingest()

• FabricKqlItem$write_table()

• FabricKqlItem$export()

• FabricKqlItem$ingestion_status()

• FabricKqlItem$ingestion_wait()

FabricKqlItem$query()

Run a KQL query.

Usage

FabricKqlItem$query(query, ...)

Arguments

Returns

A typed tibble, or a fabric_kql_tables list for multiple primary results; see fabric_kql_query().

FabricKqlItem$tables()

List KQL tables.

Usage

FabricKqlItem$tables(...)

Arguments

Returns

A table inventory tibble.

FabricKqlItem$read_table()

Read one KQL table.

Usage

FabricKqlItem$read_table(table, ...)

Arguments

Returns

A typed tibble with Kusto metadata attributes.

FabricKqlItem$ingest()

Ingest existing sources into a KQL table.

Usage

FabricKqlItem$ingest(table, sources, format, ...)

Arguments

Returns

A fabric_kql_ingestion handle.

FabricKqlItem$write_table()

Write R or Arrow data to a KQL table.

Usage

FabricKqlItem$write_table(table, data, ...)

Arguments

Returns

A fabric_kql_write_result with ingestion status and staging disposition.

FabricKqlItem$export()

Export a KQL query to Fabric storage.

Usage

FabricKqlItem$export(query, destination, ...)

Arguments

Returns

A fabric_kql_export_result with operation state, artifact paths, and record counts.

FabricKqlItem$ingestion_status()

Retrieve one KQL ingestion status snapshot.

Usage

FabricKqlItem$ingestion_status(ingestion, ...)

Arguments

Returns

A fabric_kql_ingestion_status record.

FabricKqlItem$ingestion_wait()

Wait for a KQL ingestion to finish.

Usage

FabricKqlItem$ingestion_wait(ingestion, ...)

Arguments

Returns

A terminal fabric_kql_ingestion_status record.

Super classes

FabricRecord -> FabricItem -> FabricKqlItem -> FabricEventhouse

Super classes

FabricRecord -> FabricItem -> FabricKqlItem -> FabricKqlDatabase

Super classes

FabricRecord -> FabricItem -> FabricGraphQLApi

Methods

Public methods

• FabricGraphQLApi$query()

• FabricGraphQLApi$schema()

• FabricGraphQLApi$paginate()

FabricGraphQLApi$query()

Run a GraphQL query.

Usage

FabricGraphQLApi$query(query, ...)

Arguments

Returns

A fabric_graphql_result.

FabricGraphQLApi$schema()

Retrieve the GraphQL schema.

Usage

FabricGraphQLApi$schema(...)

Arguments

Returns

A fabric_graphql_schema.

FabricGraphQLApi$paginate()

Retrieve all pages of a GraphQL cursor query.

Usage

FabricGraphQLApi$paginate(query, next_cursor, ...)

Arguments

Returns

A fabric_graphql_pages list.

Super classes

FabricRecord -> FabricItem -> FabricSemanticModel

Methods

Public methods

• FabricSemanticModel$dax_query()

• FabricSemanticModel$refresh()

• FabricSemanticModel$refresh_history()

• FabricSemanticModel$refresh_status()

• FabricSemanticModel$refresh_wait()

• FabricSemanticModel$refresh_cancel()

FabricSemanticModel$dax_query()

Run a DAX query against this semantic model.

Usage

FabricSemanticModel$dax_query(dax, ...)

Arguments

Returns

A tibble or Arrow stream.

FabricSemanticModel$refresh()

Start a refresh of this semantic model.

Usage

FabricSemanticModel$refresh(...)

Arguments

Returns

A fabric_pbi_refresh handle.

FabricSemanticModel$refresh_history()

Retrieve this semantic model's refresh history.

Usage

FabricSemanticModel$refresh_history(...)

Arguments

Returns

A fabric_pbi_refresh_history list.

FabricSemanticModel$refresh_status()

Retrieve one refresh status snapshot.

Usage

FabricSemanticModel$refresh_status(refresh, ...)

Arguments

Returns

A fabric_pbi_refresh_detail record.

FabricSemanticModel$refresh_wait()

Wait for a submitted refresh to finish.

Usage

FabricSemanticModel$refresh_wait(refresh, ...)

Arguments

Returns

A terminal fabric_pbi_refresh_detail record.

FabricSemanticModel$refresh_cancel()

Cancel a submitted refresh.

Usage

FabricSemanticModel$refresh_cancel(refresh, ...)

Arguments

Returns

TRUE, invisibly, when cancellation is accepted.

Super classes

FabricRecord -> FabricItem -> FabricJobItem

Methods

Public methods

• FabricJobItem$run()

• FabricJobItem$status()

• FabricJobItem$wait()

• FabricJobItem$cancel()

• FabricJobItem$instances()

• FabricJobItem$schedules()

• FabricJobItem$schedule_create()

• FabricJobItem$schedule_update()

• FabricJobItem$schedule_delete()

FabricJobItem$run()

Start an on-demand item job.

Usage

FabricJobItem$run(...)

Arguments

Returns

A fabric_job handle.

FabricJobItem$status()

Retrieve one job status snapshot.

Usage

FabricJobItem$status(job = NULL, ...)

Arguments

Returns

A fabric_job_instance record.

FabricJobItem$wait()

Wait for a submitted job to finish.

Usage

FabricJobItem$wait(job, ...)

Arguments

Returns

A terminal fabric_job_instance record.

FabricJobItem$cancel()

Cancel a submitted job.

Usage

FabricJobItem$cancel(job = NULL, ...)

Arguments

Returns

TRUE, invisibly, when cancellation is accepted.

FabricJobItem$instances()

Retrieve this item's job history.

Usage

FabricJobItem$instances(...)

Arguments

Returns

A fabric_job_instance_list.

FabricJobItem$schedules()

List this item's schedules.

Usage

FabricJobItem$schedules(...)

Arguments

Returns

A fabric_job_schedule_list.

FabricJobItem$schedule_create()

Create an item schedule.

Usage

FabricJobItem$schedule_create(configuration, ...)

Arguments

Returns

A fabric_job_schedule record.

FabricJobItem$schedule_update()

Update an item schedule.

Usage

FabricJobItem$schedule_update(schedule_id, configuration = NULL, ...)

Arguments

Returns

A fabric_job_schedule record.

FabricJobItem$schedule_delete()

Delete an item schedule.

Usage

FabricJobItem$schedule_delete(schedule_id, ...)

Arguments

Returns

TRUE, invisibly, after deletion.

Examples

## Not run: 
workspace <- fabric_workspaces()[[1L]]
workspace$displayName

# Equivalent function: fabric_lakehouses(workspace)
lakehouse <- workspace$lakehouses()[[1L]]
lakehouse$id
# Equivalent function: fabric_lakehouse_tables(lakehouse)
lakehouse$tables()
# Equivalent function: fabric_lakehouse_read_table(lakehouse, ...)
orders <- lakehouse$read_table("orders", limit = 100L)

# Workload-specific subclasses expose their own lifecycle methods
# Equivalent function: fabric_semantic_models(workspace)
model <- workspace$semantic_models()[[1L]]
# Equivalent function: fabric_pbi_refresh(model)
refresh <- model$refresh()
# Equivalent function: fabric_pbi_refresh_wait(refresh, ...)
model$refresh_wait(refresh, timeout = 1800)

# Equivalent generic: as.list(lakehouse)
lakehouse_record <- lakehouse$as_list()

# Fabric item types outside the typed-helper subset remain usable records
report <- workspace$items(type = "Report")[[1L]]
report$type

## End(Not run)

A Microsoft Fabric Livy batch job

Description

Represents a Spark application submitted with fabric_livy_batch_submit() Use ⁠$wait()⁠ to wait for completion, ⁠$result()⁠ or ⁠$logs()⁠ to inspect the outcome, and ⁠$cancel()⁠ to request cancellation. Most users do not need to call this 'R6' class directly. These lifecycle methods do not have separate free-function wrappers

Format

An R6::R6Class generator

Value

The FabricLivyBatch 'R6' generator.

Public fields

Methods

Public methods

• FabricLivyBatch$new()

• FabricLivyBatch$print()

• FabricLivyBatch$status()

• FabricLivyBatch$wait()

• FabricLivyBatch$logs()

• FabricLivyBatch$result()

• FabricLivyBatch$cancel()

FabricLivyBatch$new()

Internal constructor used by fabric_livy_batch_submit()

Usage

FabricLivyBatch$new(response, url, credential, verbose = TRUE)

Arguments

Returns

A new batch object

FabricLivyBatch$print()

Print a concise batch summary

Usage

FabricLivyBatch$print(...)

Arguments

Returns

self, invisibly

FabricLivyBatch$status()

Retrieve current batch metadata

Usage

FabricLivyBatch$status(refresh = TRUE, deadline = NULL)

Arguments

Returns

The raw batch response list

FabricLivyBatch$wait()

Wait for the batch to reach a terminal state

Usage

FabricLivyBatch$wait(
  timeout = 1200,
  poll_interval = 5,
  error_on_failure = TRUE,
  cancel_on_timeout = FALSE
)

Arguments

Returns

self, invisibly

FabricLivyBatch$logs()

Return available Spark driver log lines

Usage

FabricLivyBatch$logs(refresh = TRUE)

Arguments

Returns

A character vector

FabricLivyBatch$result()

Return structured batch metadata and logs

Usage

FabricLivyBatch$result(refresh = TRUE, error_on_failure = TRUE)

Arguments

Returns

A fabric_livy_batch_result list

FabricLivyBatch$cancel()

Request batch cancellation

Usage

FabricLivyBatch$cancel(deadline = NULL)

Arguments

Returns

TRUE, invisibly, after Fabric accepts the request

Examples

## Not run: 
# fabric_livy_batch_submit() returns this class for a submitted Spark job
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
scripts <- fabric_onelake_list(workspace, lakehouse, "Files/jobs")
script <- scripts[grepl("[.]py$", scripts$path), ][1L, ]
script_uri <- paste0(
  "abfss://", workspace$id, "@onelake.dfs.fabric.microsoft.com/",
  lakehouse$id, "/", script$path[[1L]]
)
batch <- fabric_livy_batch_submit(
  lakehouse,
  file = script_uri
)
inherits(batch, "FabricLivyBatch")

# Wait for completion, then inspect the application result and logs
batch$wait()
batch$result()
batch$logs()

## End(Not run)

A Microsoft Fabric Livy session

Description

A Livy session keeps Spark running while you submit several pieces of code Create one with fabric_livy_session(), call ⁠$wait()⁠ once it starts, use ⁠$run()⁠ to execute code, and call ⁠$close()⁠ when finished. Most users do not need to call this 'R6' class directly. These lifecycle methods do not have separate free-function wrappers

Format

An R6::R6Class generator

Value

The FabricLivySession 'R6' generator.

Public fields

Methods

Public methods

• FabricLivySession$new()

• FabricLivySession$print()

• FabricLivySession$status()

• FabricLivySession$wait()

• FabricLivySession$submit()

• FabricLivySession$run()

• FabricLivySession$statements()

• FabricLivySession$reset_timeout()

• FabricLivySession$close()

FabricLivySession$new()

Internal constructor used by fabric_livy_session()

Usage

FabricLivySession$new(
  livy_url,
  credential,
  payload,
  response = NULL,
  high_concurrency = FALSE,
  verbose = TRUE
)

Arguments

Returns

A new session object

FabricLivySession$print()

Print a concise session summary

Usage

FabricLivySession$print(...)

Arguments

Returns

self, invisibly

FabricLivySession$status()

Return the latest session response

Usage

FabricLivySession$status(refresh = TRUE, deadline = NULL)

Arguments

Returns

The raw session response list

FabricLivySession$wait()

Wait until the session can accept statements

Usage

FabricLivySession$wait(timeout = 600, poll_interval = 3)

Arguments

Returns

self, invisibly

FabricLivySession$submit()

Submit code without waiting for completion

Usage

FabricLivySession$submit(
  code,
  kind = c("spark", "pyspark", "sparkr", "sql"),
  source_id = NULL
)

Arguments

Returns

A FabricLivyStatement

FabricLivySession$run()

Submit code, wait, and return its parsed result

Usage

FabricLivySession$run(
  code,
  kind = c("spark", "pyspark", "sparkr", "sql"),
  source_id = NULL,
  timeout = 600,
  poll_interval = 2
)

Arguments

Returns

A fabric_livy_statement_result list

FabricLivySession$statements()

List every statement in this execution context

Usage

FabricLivySession$statements()

Returns

The raw Livy statements response

FabricLivySession$reset_timeout()

Reset a regular session's inactivity timeout

Usage

FabricLivySession$reset_timeout()

Returns

self, invisibly

FabricLivySession$close()

Release this session or high-concurrency context

Usage

FabricLivySession$close(deadline = NULL)

Arguments

Returns

TRUE when closed or FALSE when already closed, invisibly

Examples

## Not run: 
# fabric_livy_session() creates this class for a discovered Lakehouse
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
session <- fabric_livy_session(lakehouse)
inherits(session, "FabricLivySession")

# Wait before running code, and close the Spark session when finished
session$wait()
session$run("print(1 + 1)", kind = "pyspark")
session$close()

## End(Not run)

A statement submitted to a Fabric Livy session

Description

Represents one piece of code submitted to a FabricLivySession. Call ⁠$wait()⁠ and then ⁠$result()⁠ to retrieve its output. For the usual submit-and-wait workflow, use the session's ⁠$run()⁠ method instead. These lifecycle methods do not have separate free-function wrappers

Format

An R6::R6Class generator

Value

The FabricLivyStatement 'R6' generator.

Public fields

Methods

Public methods

• FabricLivyStatement$new()

• FabricLivyStatement$print()

• FabricLivyStatement$status()

• FabricLivyStatement$wait()

• FabricLivyStatement$result()

• FabricLivyStatement$cancel()

FabricLivyStatement$new()

Internal constructor used by FabricLivySession$submit()

Usage

FabricLivyStatement$new(session, response, url, credential, verbose = TRUE)

Arguments

Returns

A new statement object

FabricLivyStatement$print()

Print a concise statement summary

Usage

FabricLivyStatement$print(...)

Arguments

Returns

self, invisibly

FabricLivyStatement$status()

Retrieve statement state and available output

Usage

FabricLivyStatement$status(
  refresh = TRUE,
  from = NULL,
  size = NULL,
  deadline = NULL
)

Arguments

Returns

The raw statement response list

FabricLivyStatement$wait()

Wait for the statement to reach a terminal state

Usage

FabricLivyStatement$wait(
  timeout = 600,
  poll_interval = 2,
  error_on_failure = TRUE
)

Arguments

Returns

self, invisibly

FabricLivyStatement$result()

Return parsed output and timing metadata

Usage

FabricLivyStatement$result(
  refresh = TRUE,
  error_on_failure = TRUE,
  from = NULL,
  size = NULL
)

Arguments

Returns

A fabric_livy_statement_result list

FabricLivyStatement$cancel()

Request cancellation of this statement

Usage

FabricLivyStatement$cancel()

Returns

The raw cancellation response, invisibly

Examples

## Not run: 
# Statements are returned by a session; users do not construct them directly
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
session <- fabric_livy_session(lakehouse)
session$wait()

# Submit code, wait for it, and inspect its result
statement <- session$submit("print(40 + 2)", kind = "pyspark")
inherits(statement, "FabricLivyStatement")
statement$wait()
statement$result()
session$close()

## End(Not run)

Search the OneLake catalog

Description

Searches Fabric item metadata across every workspace visible to the caller. Results are lightweight R6 discovery objects that contain the item and workspace identity. Type-specific results expose the methods that can run from that metadata.

Usage

fabric_catalog_search(
  search = NULL,
  types = NULL,
  filter = NULL,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  output = c("r6", "list")
)

Arguments

Details

Catalog search is a preview Fabric API. It is for metadata discovery only and does not grant access to item contents. The caller needs Catalog.Read.All; Fabric returns only entries that the calling user, service principal, or managed identity is authorized to see.

Pagination sends the search parameters only on the first request and sends only the continuation token on later requests, as required by Fabric. A repeated or malformed token raises a fabric_catalog_protocol_error instead of silently returning partial results or looping indefinitely.

Value

With output = "r6", a list of FabricItem objects or type-specific subclasses. With output = "list", a list of fabric_catalog_entry records that also inherit from fabric_item. Both representations preserve the fields returned by Fabric and add the item workspace identity from the catalog hierarchy. Workspace entries returned by unfiltered browsing become FabricWorkspace objects, or fabric_catalog_entry records inheriting fabric_workspace.

References

Catalog search REST API

OneLake Catalog REST API overview

Examples

## Not run: 
# Search all visible workspaces for Lakehouses related to sales
entries <- fabric_catalog_search(
  search = "sales",
  types = "Lakehouse",
  page_size = 100
)

# `$onelake_list()` calls fabric_onelake_list()
lakehouse <- entries[[1L]]
lakehouse$onelake_list(path = "Tables")

## End(Not run)

Inspect the optional Python Delta runtime

Description

Shows whether the optional Python tools used for direct Delta reads are ready By default this does not start Python. Set initialize = TRUE to prepare the environment, check the minimum Python version and required module imports, and report installed versions. An unusable runtime raises an error with setup instructions. Use initialize = FALSE to inspect it without this check

Usage

fabric_delta_config(initialize = FALSE)

Arguments

Value

A list describing initialization state, requirements, the selected interpreter, module availability, and installed package versions when initialized. initialized only indicates whether Python has started; it does not mean the Delta dependencies are available

Use a managed environment (recommended)

For automatic installation, explicitly select a 'reticulate'-managed environment. First restart R (in RStudio: Session > Restart R), then run:

Sys.setenv(RETICULATE_PYTHON = "managed")
library(fabricQueryR)
fabric_delta_config(initialize = TRUE)

"managed" is a special setting, not an environment name or a Python path. The first line tells 'reticulate' to create or reuse a suitable environment. Loading 'fabricQueryR' declares the required Python version and packages through reticulate::py_require(). The final line starts Python, triggering 'uv' to download the runtime and dependencies if needed, and checks setup. 'reticulate' also downloads 'uv' if needed; no separate py_install() call is necessary

The restart is required if Python has already started: setting RETICULATE_PYTHON cannot switch the interpreter in a running Python session.

To keep this selection for future sessions in this project, add the line RETICULATE_PYTHON=managed to the project's .Renviron file, then restart R. Otherwise, repeat the Sys.setenv() line at the start of each R session

Without this explicit selection, a Python chosen through RStudio, environment variables, reticulate::use_python(), or a project virtualenv can take precedence over the managed environment. py_require() declares requirements but does not install them into that existing Python, and initialize = TRUE does not change that choice. For example, selecting Python 3.9 leaves the Delta requirements unmet even though Python has started. reticulate::py_config() reports the selected interpreter and why it was chosen. After the setup above succeeds, both entries in available should be TRUE and versions should report the installed Delta packages

Create a reusable environment with reticulate

For an environment you manage yourself, restart R and create a virtualenv from an installed Python 3.11. Then install the required packages into that named environment and select its interpreter before initializing Python:

reticulate::virtualenv_create("fabricQueryR", version = "3.11")
reticulate::py_install(
  c("deltalake==1.6.2", "nanoarrow==0.8.0"),
  envname = "fabricQueryR",
  method = "virtualenv"
)
Sys.setenv(
  RETICULATE_PYTHON = reticulate::virtualenv_python("fabricQueryR")
)
library(fabricQueryR)
fabric_delta_config(initialize = TRUE)

virtualenv_create() needs a compatible installed Python and reuses an existing environment of that name without upgrading its Python. If needed, install Python first with reticulate::install_python("3.11:latest") or use the 'uv' alternative below. install_python() uses 'pyenv' / 'pyenv-win'; it is separate from the automatic 'uv' setup described above

py_install() installs into the named virtualenv using 'pip'. Always pass envname to make the destination explicit. For an existing Conda environment, use ⁠method = "conda", pip = TRUE⁠ with that environment's name instead

In later R sessions, repeat the Sys.setenv() selection before using Python; installation is needed only when creating or updating the environment. reticulate::use_virtualenv() is another way to select it, but an existing RETICULATE_PYTHON setting takes precedence over that selection

Create a reusable environment with uv

If the 'uv' command-line tool is already installed and available on PATH, it can create a new project environment and download Python if necessary. From the project directory, run in a terminal:

uv venv --python 3.11 --seed .venv-fabricQueryR

--seed installs 'pip' so that reticulate::py_install() can install into the environment. In a fresh R session in the same project directory:

reticulate::py_install(
  c("numpy", "deltalake==1.6.2", "nanoarrow==0.8.0"),
  envname = "./.venv-fabricQueryR",
  method = "virtualenv"
)
Sys.setenv(
  RETICULATE_PYTHON = reticulate::virtualenv_python("./.venv-fabricQueryR")
)
library(fabricQueryR)
fabric_delta_config(initialize = TRUE)

The ⁠./⁠ makes this a project path rather than a named environment under the virtualenv directory used by 'reticulate'. 'numpy' is included because 'uv' does not install it automatically

This environment is managed by you; 'reticulate' does not resolve py_require() declarations into it. Use py_install() with that explicit envname, or ⁠uv pip install --python .venv-fabricQueryR ...⁠, to update it. See the uv environment guide for details

Install into an existing standalone Python

Select Python 3.10 or newer before initialization. Install the Python dependencies into that exact interpreter, for example from R:

system2("/path/to/python", c(
  "-m", "pip", "install", "deltalake==1.6.2", "nanoarrow==0.8.0"
))

On Windows, use the full path to python.exe with forward slashes. Restart R, select that interpreter with reticulate::use_python(), then run fabric_delta_config(initialize = TRUE) to verify setup

Examples

# Inspect requirements without starting Python or downloading anything
config <- fabric_delta_config()
config[c("initialized", "requirements", "available")]

Invoke a published Fabric user data function

Description

Usage

fabric_function_invoke(
  function_url,
  parameters = list(),
  timeout = 110,
  idempotent = FALSE,
  max_response_bytes = .fabric_function_response_limit,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL
)

Arguments

Details

Calls the public REST endpoint for one published Microsoft Fabric user data function and returns the service's synchronous execution result. Function definition, publication, and deployment are intentionally outside this helper's scope.

This invocation API is experimental because its request and response handling is covered by offline tests, but the package cannot currently maintain repeatable end-to-end coverage against published functions. The package's development sandbox uses a service principal, while Fabric's User Data Function create, update-definition, and delete APIs currently support delegated user identities only. The sandbox therefore cannot provision and maintain the published public-function fixtures needed for that coverage.

Value

A fabric_function_result list with function_name, invocation_id, status, output, errors, http_status, and response. Function output is not redacted because field names such as token can be legitimate domain data. Unsafe whole-number JSON values are exact character text; decimal JSON values use ordinary R doubles. The rest of response is redacted and retains unknown future fields. Inspect status and errors; receiving a result does not by itself mean the function succeeded.

Before you invoke

Publish the user data functions item, switch it to Run only mode, enable Public access for the function, and copy its Public URL from the Fabric portal. Pass that complete URL to function_url; item discovery does not currently expose enough information to derive a public function URL safely.

Parameter names and values must match the published Python signature. Fabric supports JSON strings, ISO 8601 datetime strings, booleans, numbers, arrays, and objects as inputs. The top-level parameters object therefore needs unique, non-empty camelCase names without underscores. Python keywords and Fabric's reserved req, context, and reqInvocationId names are rejected before a request is sent. A named atomic vector is converted to a named list; use I() around a one-element value when it must remain a JSON array. Supply datetimes as ISO 8601 strings with an explicit timezone and the desired fractional seconds. R POSIXct and POSIXlt objects are rejected, including inside lists and data frames, to avoid lossy JSON conversion.

Permissions and authentication

Delegated authentication defaults to the narrower Power BI permission UserDataFunction.Execute.All. Microsoft also accepts the broader Item.Execute.All permission; use it only when the app registration grants that scope, and pass its full scope URL explicitly through audience. Either delegated scope still requires Execute permission on the user data functions item. Service-to-service callers can use an application credential with the Power BI .default audience and the required tenant and item access.

Application authentication for the public invocation endpoint is distinct from authentication used by connections inside the function. Microsoft currently does not support using a service principal through connections managed by user data functions to access Fabric items or data sources. A service principal can therefore invoke a compatible function while a function that relies on an unsupported managed connection can still fail.

The function URL is a credential boundary. Tokens are sent to the explicitly supplied HTTPS endpoint. URLs containing credentials, query parameters, fragments, or nonstandard ports are rejected. HTTPS and route validation do not prove hostname ownership or token audience. Use a custom host only when your organization controls it, with a token or provider issued for that host's intended audience.

Results, retries, and limits

Fabric reports Succeeded, BadRequest, Failed, Timeout, and ResponseTooLarge through one response envelope. Valid envelopes remain inspectable as fabric_function_result objects even when Fabric uses a non-success HTTP status. Authentication, authorization, throttling, and malformed service responses continue to raise the package's typed HTTP or response errors. The documentation describes an error name, while current responses can use errorCode; errors adds name as an alias when needed and response retains the original service shape.

Invocations are not retried by default because functions can have arbitrary side effects. Set idempotent = TRUE only when repeating the function is safe; this enables the package's bounded retries for transport failures, throttling, and transient HTTP responses.

Fabric limits public-endpoint execution to 100 seconds, request parameters to 4 MB, and a function's return value to 30 MB. The default 110-second client timeout allows the service timeout response to arrive. The 32 MiB client response cap leaves room for Fabric's envelope around a 30 MB output. Secret-named fields and bearer-token text are redacted recursively from errors, response metadata, and conditions. Function output is domain data and is not redacted, even when it contains secret-like field names. Unsafe whole-number JSON values are returned as exact character text; decimal JSON values use ordinary R doubles.

References

Invoke user data functions from a Python application

Fabric user data functions service limits

Fabric user data function programming model

Examples

## Not run: 
# Discover the user data functions item that owns the published function
workspace <- fabric_workspaces()[[1L]]
function_item <- fabric_user_data_functions(workspace)[[1L]]
function_item$displayName

# Discovery cannot expose a function URL yet. Copy the published function's
# complete Invoke URL from this item's Run-only settings into this variable
function_url <- Sys.getenv("FABRIC_FUNCTION_URL")

# Parameter names must match the published Python function signature
result <- fabric_function_invoke(
  function_url,
  parameters = list(
    customerName = "Ada",
    order = list(id = 42L, lines = I(c("A", "B")))
  )
)

# Inspect the output and any function-level errors returned by Fabric
result$status
result$output
result$errors

## End(Not run)

Collect paged GraphQL row objects into a tibble

Description

Combines row objects from a caller-selected field in every result returned by fabric_graphql_paginate(). The explicit path is relative to each page's data field because GraphQL response shapes are schema-defined and cannot be inferred safely

Usage

fabric_graphql_collect(pages, path)

Arguments

Details

Scalar fields become ordinary tibble columns. Nested objects and arrays stay as list-columns and are never flattened. Fields introduced on later pages are added in first-seen order, with missing or GraphQL null scalar values represented by typed NA values when their type can be inferred. Exact integer strings returned by fabric_graphql_query() remain character data; finite numeric entries in the same field, including fractions, are promoted to character using text that recovers the received R value exactly. Fields containing only numeric values retain ordinary numeric columns. Nullable row elements retain their positions as missing rows; the null_rows attribute records their one-based positions, distinguishing them from objects whose fields are all null.

A successful result has class fabric_graphql_rows and reports completion, page count, path, and GraphQL errors in its printed header and attributes. Use attr(rows, "errors") to inspect partial GraphQL errors. If pagination stopped before next_cursor reported completion, including at max_pages, the function raises fabric_graphql_collection_error; its partial_data field contains the rows collected so far and is explicitly marked incomplete

Value

A fabric_graphql_rows tibble. Attributes complete, errors, page_count, path, and null_rows retain collection metadata

References

Fabric API for GraphQL limits

Fabric GraphQL aggregation and pagination shape

Examples

## Not run: 
# Discover the GraphQL API, then fetch every Products page
workspace <- fabric_workspaces()[[1L]]
api <- fabric_graphql_apis(workspace)[[1L]]
pages <- fabric_graphql_paginate(
  api,
  query = paste(
    "query Products($first: Int!, $after: String) {",
    "  products(first: $first, after: $after) {",
    "    items { id name details { category } }",
    "    hasNextPage endCursor",
    "  }",
    "}"
  ),
  variables = list(first = 100L, after = NULL),
  next_cursor = fabric_graphql_cursor("products")
)

# Combine nested item rows from every page into one tibble
rows <- fabric_graphql_collect(pages, c("products", "items"))
attr(rows, "complete")
attr(rows, "errors")

## End(Not run)

Locate pagination information in a GraphQL result

Description

Creates the next_cursor function used by fabric_graphql_paginate() for the common hasNextPage and endCursor pagination fields

Usage

fabric_graphql_cursor(path, has_next = "hasNextPage", end_cursor = "endCursor")

Arguments

Value

A function suitable for next_cursor in fabric_graphql_paginate(). For each page it returns the cursor when has_next is true, otherwise NULL

Examples

# Build a reusable extractor for a GraphQL connection named "products"
next_cursor <- fabric_graphql_cursor("products")

# This small local result shows the response shape expected by the extractor
page <- structure(
  list(data = list(products = list(
    hasNextPage = TRUE,
    endCursor = "opaque-cursor"
  ))),
  class = c("fabric_graphql_result", "list")
)

# TRUE plus a cursor tells the paginator to request another page
next_cursor(page)

Read all pages from a Fabric GraphQL query

Description

Repeats fabric_graphql_query() until the API reports that no more pages are available. Because every GraphQL schema can store pagination information in a different place, next_cursor tells the function where to find it

Usage

fabric_graphql_paginate(
  api,
  query,
  next_cursor,
  variables = list(),
  cursor_variable = "after",
  operation_name = NULL,
  workspace_id = NULL,
  error_policy = c("return", "warn", "error"),
  max_pages = 100L,
  timeout = 110,
  idempotent = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  api_base = .fabric_api_base,
  numeric_policy = c("exact", "double")
)

Arguments

Details

Failures while paging raise fabric_graphql_pagination_error, retaining incomplete pages, the failing result (when available), request variables, cursor, seen_cursors, page_number, and the original condition as parent. Error-only GraphQL responses cannot continue pagination, even with error_policy = "return". Partial data with usable cursors remains supported.

Value

A fabric_graphql_pages list with pages, combined errors, and the final variables. pages contains one fabric_graphql_result per request and complete is TRUE when the callback reported no next page Results are kept page-by-page because the requested schema shape can vary

Examples

## Not run: 
# Discover the GraphQL API that exposes the Products query
workspace <- fabric_workspaces()[[1L]]
api <- fabric_graphql_apis(workspace)[[1L]]

# Fetch pages until the helper sees no next cursor
pages <- fabric_graphql_paginate(
  api,
  query = paste(
    "query Products($first: Int!, $after: String) {",
    "  products(first: $first, after: $after) {",
    "    items { id name } hasNextPage endCursor",
    "  }",
    "}"
  ),
  variables = list(first = 100L, after = NULL),
  next_cursor = fabric_graphql_cursor("products")
)
pages$complete

## End(Not run)

Run a query against a Fabric GraphQL API

Description

Sends a GraphQL query or mutation to an API for GraphQL item and returns the result as a nested R list. Use this when a Fabric API already exposes the Lakehouse, Warehouse, or SQL Database data you need

Usage

fabric_graphql_query(
  api,
  query,
  variables = list(),
  operation_name = NULL,
  workspace_id = NULL,
  error_policy = c("return", "warn", "error"),
  timeout = 110,
  idempotent = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  api_base = .fabric_api_base,
  numeric_policy = c("exact", "double")
)

Arguments

Value

A fabric_graphql_result list with data, errors, extensions, and response (the complete parsed response). data follows the nested shape requested in the GraphQL document and is usually a combination of named lists and vectors, not a tibble. Because GraphQL can return partial data, inspect errors even when data is present

Before you query

Before using this function, create an API for GraphQL item in a Fabric workspace, connect its data source, and choose which tables, fields, queries, and mutations the API exposes. Fabric's built-in GraphQL editor and schema explorer are the easiest places to design and test a document before copying it to R

Mutation availability depends on the configured source. Fabric Warehouse and SQL Database sources can expose supported mutations, while Lakehouse and mirrored SQL analytics endpoint sources are read-only and expose queries only

The easiest input is an item from fabric_graphql_apis(). You can instead supply the API's endpoint, or its ID together with workspace_id

Permissions and authentication

Interactive authentication requires the Power BI delegated scope GraphQLApi.Execute.All, plus Run Queries and Mutations permission on the API. Service principals are also supported by Fabric: request a Fabric API token with auth_args or pass one through token, enable service principals for Fabric APIs in the tenant, and grant the principal API Execute access or a suitable workspace role. With SSO connectivity, the caller also needs the required access to the underlying data source Saved-credential APIs use the configured connection instead

Most users can leave audience = NULL; 'fabricQueryR' chooses the documented scope for the sign-in flow. Set it only for a custom identity provider. HTTPS and URL-shape validation do not prove hostname ownership or token audience. Use a custom API Management or gateway host only when your organization controls it, with a token or provider issued for that host's intended audience

Retries and service limits

GraphQL POST requests are not retried by default because a document can contain mutations. Set idempotent = TRUE only when the operation is safe to repeat

Fabric returns at most 100 items by default and permits at most 100,000 items across pagination. Each response is limited to 64 MB, each request to 100 seconds, and query nesting to 10 levels. Use smaller pages and filtered query partitions when a result could approach these service limits. One GraphQL API item can have at most 1,000 source objects attached across its data sources; this is not a limit of 1,000 data sources. Split objects from multiple sources across multiple API items, or use stored procedures or another abstraction for a single large source

Large integers outside R's exact numeric range are returned as character values so identifiers and other large integer fields are not rounded. By default, JSON numbers containing a decimal point or exponent are also returned as their exact source text, retaining precision, scale, trailing zeros, and exponent spelling. Set numeric_policy = "double" to decode those values as ordinary R doubles instead

References

Fabric API for GraphQL editor

Fabric GraphQL schema explorer

Use service principals with Fabric API for GraphQL

Fabric API for GraphQL limits

Examples

## Not run: 
# Discover an API for GraphQL item instead of copying its endpoint or ID
workspace <- fabric_workspaces()[[1L]]
api <- fabric_graphql_apis(workspace)[[1L]]

# Keep the filter value in variables rather than inserting it into the query
result <- fabric_graphql_query(
  api,
  query = paste(
    "query Products($category: String!) {",
    "  products(filter: {category: {eq: $category}}) {",
    "    items { id name category }",
    "  }",
    "}"
  ),
  variables = list(category = "A"),
  operation_name = "Products"
)

# GraphQL can return data and errors in the same response; inspect both
result$data$products$items
result$errors

## End(Not run)

Inspect a Fabric GraphQL schema

Description

Runs the standard GraphQL introspection query against an API for GraphQL item. The returned schema retains the service's nested type references, fields, input values, enum values, and directives so callers can explore the API without assuming how Fabric named its generated objects

Usage

fabric_graphql_schema(
  api,
  workspace_id = NULL,
  timeout = 110,
  idempotent = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  api_base = .fabric_api_base,
  numeric_policy = c("exact", "double")
)

Arguments

Details

Microsoft Fabric disables runtime introspection by default. A workspace administrator must enable it under API Settings > Introspection. When it must remain disabled, use Export schema in the Fabric portal instead; schema export remains available independently of the runtime setting

Value

A fabric_graphql_schema list containing the standard ⁠__schema⁠ fields. The original GraphQL response and its (normally empty) errors are available in the response and errors attributes

References

Fabric API for GraphQL introspection and schema export

Examples

## Not run: 
# Discover the GraphQL API whose schema you want to inspect
workspace <- fabric_workspaces()[[1L]]
api <- fabric_graphql_apis(workspace)[[1L]]

# Request the standard GraphQL introspection schema
schema <- fabric_graphql_schema(api)

# List its named types to learn what can be queried
vapply(schema$types, `[[`, character(1), "name")

## End(Not run)

Discover one Microsoft Fabric item

Description

Finds one item and returns the connection details needed by 'fabricQueryR' Use this when you know the item's name or ID and do not need to list every item in the workspace

Usage

fabric_item(
  workspace,
  item,
  type = NULL,
  detail = NULL,
  detail_errors = c("abort", "record"),
  include = NULL,
  personal_workspace_tenant_id = NULL,
  personal_workspace_owner = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  output = c("r6", "list")
)

Arguments

Details

GUID-based lookup requires read access to the item. A workspace GUID is used directly without requesting workspace details, so directly shared items do not require a workspace role. Name lookup requires permission to list the relevant workspaces or items. To reuse workspace-specific endpoints, pass a discovered workspace object; alternatively, supply api_base explicitly. Workload-specific enrichment additionally requires Item.Read.All/Item.ReadWrite.All or the applicable workload-specific read scope and access to the item. Microsoft currently limits User Data Function detail retrieval to delegated user identities, so its automatic default is lightweight. Set detail = TRUE explicitly when using a supported identity

Value

With output = "r6", a FabricItem object or type-specific subclass. With output = "list", one fabric_item record containing the item's name, ID, type, workspace, and available connection details

References

Get item REST API

Examples

## Not run: 
# Discover a workspace and obtain a lightweight Warehouse object
workspace <- fabric_workspaces()[[1L]]
warehouses <- workspace$items(type = "Warehouse")

# Enrich that discovered object with connection details
warehouse <- fabric_item(workspace, warehouses[[1L]])

# `$sql_connection_info()` calls fabric_sql_connection_info()
warehouse$sql_connection_info()

## End(Not run)

Discover Microsoft Fabric items

Description

Returns the Lakehouses, Warehouses, semantic models, notebooks, and other items stored in a workspace. Every item type returned by Fabric's core list API can be represented. Where the package has a specialized R6 subclass, its methods perform the matching query, connection, file, Spark, or job operations; other types remain complete generic FabricItem records

Usage

fabric_items(
  workspace,
  type = NULL,
  detail = FALSE,
  detail_errors = c("record", "abort"),
  recursive = TRUE,
  root_folder_id = NULL,
  include = NULL,
  personal_workspace_tenant_id = NULL,
  personal_workspace_owner = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  output = c("r6", "list")
)

Arguments

Details

The caller needs at least access to the workspace (the Viewer role is sufficient for the core list operation). Workload enrichment additionally requires Item.Read.All/Item.ReadWrite.All or the corresponding workload-specific read scope and access to the item Personal-workspace semantic models use Microsoft's v2 XMLA endpoint and require both personal_workspace_tenant_id and personal_workspace_owner

Value

A list with one item object per match. Every object includes common fields such as id, displayName, type, and workspaceId. With output = "r6", results are FabricItem objects or type-specific subclasses. With output = "list", results are fabric_item lists. With detail = TRUE, both representations include connection details when Fabric makes them available

Generic and typed discovery

fabric_items() and workspace$items() are the broad, future-compatible discovery interfaces. Their optional type filter is passed to Fabric, and item types without package-specific methods are returned as FabricItem objects with all service fields, ⁠$details()⁠, and ⁠$as_list()⁠.

The helpers documented in fabric_typed_items are an intentional convenience subset of Fabric's larger and evolving item catalog. A typed helper means that the package knows the item-type spelling and workload Get route; it does not necessarily mean that the result has its own R6 subclass. See fabric_typed_items for the exact support matrix

References

List items REST API

Fabric item management overview

Personal-workspace XMLA endpoints

Examples

## Not run: 
# Start by discovering a workspace instead of copying its ID
workspaces <- fabric_workspaces()
workspace <- workspaces[[1L]]

# `$items()` is the object interface to fabric_items()
items <- workspace$items()
vapply(items, `[[`, character(1), "displayName")

# `$lakehouses()` calls fabric_lakehouses(); `$tables()` calls
# fabric_lakehouse_tables()
lakehouse <- workspace$lakehouses()[[1L]]
lakehouse$tables()

## End(Not run)

Inspect Microsoft Fabric job history

Description

Lists recent and active job instances for a Fabric item. All pages returned by Fabric are collected, and each result can be passed directly to fabric_job_status(), fabric_job_wait(), or fabric_job_cancel().

Usage

fabric_job_instances(
  item,
  workspace = NULL,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

Arguments

Details

Reading history requires an item read permission. The returned records keep an in-process reference to the supplied credential so they can be refreshed, waited on, or cancelled. That credential is not retained when a record is serialized.

Value

A list of fabric_job_instance records. Fabric usually retains at most 100 recently completed instances per item, plus active instances. Unknown future status and invocation values are returned unchanged.

References

List item job instances

Examples

## Not run: 
# Discover the Notebook whose run history you want to inspect
workspace <- fabric_workspaces()[[1L]]
notebook <- fabric_notebooks(workspace)[[1L]]

# List runs, then refresh one returned job record
history <- fabric_job_instances(notebook)
history[[1]]$status
fabric_job_status(history[[1]])

## End(Not run)

Run and monitor Microsoft Fabric item jobs

Description

Start a Notebook, data pipeline, Spark job definition, or another supported Fabric item from R. The related functions check its progress, wait for it to finish, or request cancellation. Use Fabric's scheduler for recurring runs

Usage

fabric_job_run(
  item,
  workspace = NULL,
  job_type = NULL,
  item_type = NULL,
  parameters = NULL,
  parameter_types = NULL,
  execution_data = NULL,
  default_lakehouse = NULL,
  default_lakehouse_workspace = NULL,
  compute = NULL,
  session_tag = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  .sleep = Sys.sleep,
  .now = Sys.time
)

fabric_job_status(
  job = NULL,
  workspace = NULL,
  item = NULL,
  job_instance_id = NULL,
  item_type = NULL,
  job_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  respect_retry_after = TRUE,
  notebook_details = FALSE,
  .sleep = Sys.sleep,
  .now = Sys.time
)

fabric_job_wait(
  job,
  poll_interval = NULL,
  timeout = 600,
  error_on_failure = TRUE,
  cancel_on_timeout = FALSE,
  cancel = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  notebook_details = FALSE,
  .sleep = Sys.sleep,
  .now = Sys.time
)

fabric_job_cancel(
  job = NULL,
  workspace = NULL,
  item = NULL,
  job_instance_id = NULL,
  item_type = NULL,
  job_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

Arguments

Value

fabric_job_run() returns a fabric_job handle for use with the other job functions fabric_job_status() and fabric_job_wait() return a fabric_job_instance record with status, times, failure information, and a notebook exit value when available. fabric_job_cancel() invisibly returns TRUE after Fabric accepts or confirms the cancellation

Typical workflow

Start a job with fabric_job_run(), then pass the returned handle to fabric_job_wait(). The handle keeps the workspace, item, job type, and sign-in context, so later calls do not need those details again Parameterized Core jobs can return a collection Location without an instance GUID. In that documented case, fabric_job_run() honors Retry-After and polls recent job history for one matching manual run. If the accepted instance cannot be resolved safely, it raises a fabric_job_accepted_unresolved condition rather than implying that the run request failed or replaying it

High-concurrency notebooks

A session_tag lets related notebook runs share Spark compute, but Fabric may report a failed statement as a completed shared session with no exit value Omit the tag when job status must reliably signal notebook failure. Otherwise, have the notebook report its outcome with notebookutils.notebook.exit(). The former mssparkutils namespace remains backward compatible but Microsoft recommends migrating because it will be retired

Notebook submission uses the released workload-specific route so Fabric applies per-run parameters and compute settings. Status and waiting use the stable Core endpoint by default. Set notebook_details = TRUE to opt into the beta Notebook status endpoint when exit values or workload-specific properties are required; the Core endpoint remains its fallback.

Permissions and status handling

Running and cancelling need an item execute permission. Checking or waiting also needs an item read permission, as does resolving a parameterized run's collection Location. For a parameterized Notebook, 'fabricQueryR' captures recent history before submission so a collection Location cannot be confused with an earlier run. Recovery requires response correlation with the job's root activity ID; history alone cannot establish ownership. Recovery stops with an accepted-but-unresolved error if correlation is absent or ambiguous. 'fabricQueryR' reconciles notebook status information from Fabric before returning it and stops with a typed error if Fabric reports an unfamiliar state instead of waiting indefinitely

References

Core Job Scheduler REST API

Run an on-demand item job

Run an on-demand notebook

Get a Notebook job instance (beta)

Manage and execute notebooks with public APIs

Fabric job scheduler

Examples

## Not run: 
# Discover the workspace and Notebook that will be run
workspace <- fabric_workspaces()[[1L]]
notebook <- fabric_notebooks(workspace)[[1L]]

# Start the discovered Notebook and keep the returned job handle
job <- fabric_job_run(notebook)

# Refresh the current state without waiting for completion
current <- fabric_job_status(job)
current$status

# Opt into beta Notebook details only when an exit value is required
completed <- fabric_job_wait(
  job,
  timeout = 900,
  notebook_details = TRUE
)
completed$status
completed$exit_value

# A separate active run can be cancelled when it is no longer needed
job_to_cancel <- fabric_job_run(notebook)
fabric_job_cancel(job_to_cancel)

## End(Not run)

Build a Microsoft Fabric job schedule configuration

Description

Creates a validated configuration for fabric_job_schedule_create() or fabric_job_schedule_update(). Recurrence clock times use the supplied Windows time-zone identifier, while schedule boundaries are sent to Fabric in UTC.

Usage

fabric_job_schedule_config(
  type = "Cron",
  start_time,
  end_time,
  time_zone = "UTC",
  interval = NULL,
  times = NULL,
  weekdays = NULL,
  recurrence = NULL,
  day_of_month = NULL,
  week_index = NULL,
  weekday = NULL
)

Arguments

Details

A Cron schedule is Fabric's minute-interval schedule; this function does not accept a cron expression because the REST API does not use one. Daylight saving behavior is controlled by Fabric using time_zone, not by the R process's local time zone. Arguments that do not belong to the selected documented schedule type are rejected.

Non-UTC firing remains unverified in the package's persistent Fabric sandbox: enabled Amsterdam schedules have not produced the expected run within the test window. The cause has not been established. Monthly recurrence and nonexistent or repeated local times at daylight-saving transitions also lack live execution evidence. Verify a scheduled run through fabric_job_instances() in the target workspace before relying on these configurations; successful schedule creation only confirms API acceptance.

Value

A named list using the Fabric ScheduleConfig JSON field names.

References

Create item schedule

Windows default time zones

Examples

# Describe a schedule in the Windows time zone used by Fabric
daily <- fabric_job_schedule_config(
  "Daily",
  start_time = "2026-10-01T00:00:00Z",
  end_time = "2027-10-01T00:00:00Z",
  time_zone = "W. Europe Standard Time",
  times = c("08:30", "17:00")
)

Manage Microsoft Fabric item schedules

Description

List, create, update, or delete recurring schedules for a supported Fabric item. Use fabric_job_schedule_config() to construct the four schedule types in the current REST contract.

Usage

fabric_job_schedules(
  item,
  workspace = NULL,
  job_type = NULL,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

fabric_job_schedule_create(
  item,
  configuration,
  workspace = NULL,
  job_type = NULL,
  item_type = NULL,
  enabled = TRUE,
  execution_data = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

fabric_job_schedule_update(
  item,
  schedule_id,
  configuration = NULL,
  workspace = NULL,
  job_type = NULL,
  item_type = NULL,
  enabled = NULL,
  execution_data = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

fabric_job_schedule_delete(
  item,
  schedule_id,
  workspace = NULL,
  job_type = NULL,
  item_type = NULL,
  confirm = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

Arguments

Details

Schedule deletion is not replayed after an ambiguous transport failure. An already absent schedule is treated as deleted.

List operations need an item read permission. Create and update require item execute and read-write permissions; delete requires item read-write permission. The current service limit is 20 schedules per item.

fabric_job_schedule_update() accepts partial R input for convenience, but the Fabric PATCH contract requires enabled and a complete configuration. When either is omitted, the function first reads the current schedule and preserves the omitted value. Omitted configuration and omitted or NULL execution_data are replayed from the original response JSON, retaining numeric precision and empty objects or arrays; supply a named list to replace either value. Decoded record fields use ordinary R JSON types and cannot represent arbitrary decimals.

The published REST response currently exposes enabled but no standard auto-disable reason. auto_disabled is therefore NA unless Fabric returns an explicit marker. The complete response stays available in raw.

Semantic-model refresh schedules use the Power BI dataset schedule API, not the Fabric Core Job Scheduler. These functions reject a discovered semantic model unless job_type is supplied explicitly for a future or custom route.

Value

fabric_job_schedules() returns a list of fabric_job_schedule records. Create and update return one such record. Delete invisibly returns TRUE. Records expose normalized common fields and retain the complete service response in raw.

References

Fabric Job Scheduler REST API

Update a semantic-model refresh schedule

Schedule a Data Pipeline

Schedule Dataflow Execute

Schedule Dataflow Apply Changes

Schedule a Lakehouse materialized Lake View refresh

Schedule a Data Build Tool Job

Fabric Data Pipeline REST API capabilities

Fabric job scheduler behavior

Examples

## Not run: 
# Discover the Notebook instead of copying workspace and item IDs
workspace <- fabric_workspaces()[[1L]]
notebook <- fabric_notebooks(workspace)[[1L]]

# Inspect existing schedules before creating another one
existing <- fabric_job_schedules(notebook)

# Build a weekly configuration using Fabric's Windows time-zone name
configuration <- fabric_job_schedule_config(
  "Weekly",
  start_time = "2026-10-01T00:00:00Z",
  end_time = "2027-10-01T00:00:00Z",
  time_zone = "W. Europe Standard Time",
  times = "07:30",
  weekdays = c("Monday", "Thursday")
)

# Create, disable, and finally delete the schedule returned by Fabric
schedule <- fabric_job_schedule_create(notebook, configuration)
fabric_job_schedule_update(notebook, schedule, enabled = FALSE)
fabric_job_schedule_delete(notebook, schedule, confirm = TRUE)

## End(Not run)

Export a KQL query directly to external storage

Description

Runs Kusto's server-side ⁠.export to storage⁠ command and waits for its asynchronous operation to finish. This avoids returning a large query result through R and the Kusto client-result channel. A discovered Fabric item plus a ⁠Files/⁠ directory is converted to a OneLake connection string using caller impersonation; a complete documented Kusto storage connection string can also be supplied.

Usage

fabric_kql_export(
  cluster,
  query,
  destination,
  database = NULL,
  workspace = NULL,
  path = NULL,
  item_type = NULL,
  format = c("parquet", "csv", "tsv", "json"),
  compressed = TRUE,
  include_headers = NULL,
  name_prefix = NULL,
  file_extension = NULL,
  encoding = NULL,
  compression_type = NULL,
  distribution = c("per_shard", "per_node", "single"),
  size_limit = 1e+08,
  parquet_row_group_size = NULL,
  parquet_datetime_precision = NULL,
  timeout = 900,
  poll_interval = 2,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  numeric_policy = c("exact", "service"),
  .sleep = Sys.sleep,
  .now = Sys.time
)

Arguments

Value

A fabric_kql_export_result containing the operation state, redacted destination, artifact paths, per-artifact record counts, and aggregate record count.

Tracking and failure safety

The export submission is sent once and is never automatically replayed. The function polls ⁠.show operations⁠ until Kusto reports a terminal state, then calls ⁠.show operation ... details⁠ for the authoritative artifact paths and record counts. Kusto does not remove files written before a failed export, so a failure or timeout identifies the destination and operation ID but never reports partial files as a successful result. If Kusto has already reported Completed but the artifact-details request exhausts the client deadline, the resulting details-timeout condition records operation_completed = TRUE; it does not imply that the export is still running or failed.

Storage connection strings are emitted as obfuscated Kusto string literals and are redacted from returned objects and conditions. If a submission fails before its operation ID is received, inspect the destination and Kusto operation history before trying again.

Output properties

format supports Kusto's parquet, csv, tsv, and json exporters. compressed = TRUE enables the selected compression_type, or Kusto's default codec when it is omitted. size_limit is the uncompressed target size of each artifact and must be from 100 MB through 4 GB. Text header and encoding options, and Parquet row-group and datetime-precision options, are accepted only for their applicable formats.

Decimal Parquet safety

By default, Parquet exports first request the query's output schemas without changing its text. Any decimal output raises fabric_kql_export_decimal_error before export submission, including an empty decimal result. Kusto can silently replace large decimals with zero and truncate fractional digits when exporting to Parquet; Completed only confirms the operation completed. Failed or unrecognized schema responses also stop the export. The schema check does not lock a query's schema against changes between the check and export requests.

To retain decimal values, explicitly project them as strings in your query, for example ⁠| project value_text=tostring(value), value_is_null=isnull(value)⁠. The companion null flag is necessary because tostring() turns a null into an empty string. This preserves Kusto's decimal value text, including any canonicalization already applied by the service, rather than its original input precision or scale. Alternatively, explicitly select numeric_policy = "service" to accept Kusto's Parquet conversion. The policy is also forwarded by an Eventhouse or KQLDatabase item's ⁠$export()⁠ method. Other export formats retain their service-defined conversion behavior.

Permissions

The caller needs at least Kusto Database Viewer permission. OneLake caller impersonation additionally needs write access equivalent to Storage Blob Data Contributor on the destination.

References

Kusto export to storage

Kusto storage connection strings

Kusto management HTTP request

Show Kusto operations

Kusto request properties

Examples

## Not run: 
# Discover both the source KQL database and destination Lakehouse
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
table <- Sys.getenv("FABRIC_KQL_TABLE")
table_literal <- jsonlite::toJSON(table, auto_unbox = TRUE)

# Export a bounded query to a new folder in the discovered Lakehouse
exported <- fabric_kql_export(
  database,
  query = paste0("table(", table_literal, ") | take 10000"),
  destination = lakehouse,
  path = "Files/exports/events-weekly",
  format = "parquet",
  parquet_datetime_precision = "microsecond",
  name_prefix = "events"
)
exported$artifacts

## End(Not run)

Submit and monitor tracked Eventhouse ingestion

Description

Queue existing blob or OneLake files for ingestion into an existing KQL table, then inspect or wait for the tracked per-file result. These functions use Kusto's queued-ingestion REST API, which is currently in preview

Usage

fabric_kql_ingest(
  cluster,
  table,
  sources,
  database = NULL,
  format,
  source_ids = NULL,
  raw_sizes = NULL,
  mapping = NULL,
  tags = character(),
  ingest_if_not_exists = character(),
  ignore_first_record = FALSE,
  skip_batching = FALSE,
  delete_after_download = FALSE,
  creation_time = NULL,
  validation_policy = NULL,
  zip_pattern = NULL,
  timestamp = NULL,
  timeout = 60,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  .deadline = NULL,
  .now = Sys.time
)

fabric_kql_ingestion_status(
  ingestion,
  cluster = NULL,
  database = NULL,
  table = NULL,
  details = TRUE,
  wait = FALSE,
  timeout = 900,
  poll_interval = 2,
  error_on_failure = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  .sleep = Sys.sleep,
  .now = Sys.time,
  .deadline = NULL
)

Arguments

Value

fabric_kql_ingest() returns a fabric_kql_ingestion handle with the operation ID and source IDs. fabric_kql_ingestion_status() returns a fabric_kql_ingestion_status record with normalized counts, state, UTC times, and an optional details tibble

Sources and storage access

fabric_kql_ingest() never uploads local data or serializes an R object. Every sources value must already identify a file in blob storage or OneLake, and table must already exist. Use fabric_kql_write_table() when the data is a data frame, tibble, or Arrow object; that function performs staging and can create the target with create_if_missing = TRUE.

sources can be a character vector of storage connection strings, a data frame with url, source_id, and optional raw_size columns, or a list of records with those fields. The camel-case service names sourceId and rawSize are also accepted. Character inputs use the parallel source_ids and raw_sizes arguments

Only existing ⁠https://⁠ or ⁠abfss://⁠ storage sources are accepted. Nonpublic sources must include a Kusto-supported authentication suffix or credential in the storage connection string. For example, append ⁠;impersonate⁠ to a OneLake URL when the caller has permission to read it

Source IDs are generated when omitted and are returned in the ingestion handle. They identify blobs in status details, but they are not by themselves an exactly-once guarantee

Delivery and idempotency

Queued ingestion has at-least-once delivery semantics. Submission is therefore not automatically replayed after throttling, network failure, or an ambiguous response. Retain the returned operation ID before starting unrelated work

For idempotent ingestion, submit one source per call and set ingest_if_not_exists to one or more stable keys for that source. The function also attaches the corresponding ⁠ingest-by:⁠ tags unless they are already present. A later submission with a matching key is observable in detailed status instead of silently duplicating a committed extent. The function rejects keys for multi-source requests because Kusto applies the shared properties to every source and ingests tagged sources independently. Idempotency checks can race when the same key is queued concurrently, so serialize submissions that share a key

Tracking and failures

fabric_kql_ingestion_status() accepts the handle returned by fabric_kql_ingest() or a raw operation ID plus the ingestion target. With wait = FALSE, it returns one snapshot. With wait = TRUE, it polls until every expected source is terminal or timeout is reached

The returned status distinguishes Succeeded, PartiallySucceeded, Failed, Canceled, PartiallyCanceled, and InProgress. Detailed blob failures retain error_code, failure_status, and message. Source URLs and raw service data are redacted so SAS tokens and embedded credentials are not retained in the result. Set error_on_failure = FALSE to inspect a terminal failure instead of receiving a typed condition carrying the same status in last_status. When a submission handle supplies the expected blob count, completion requires the documented status counts to match it exactly. Unknown nonzero status categories and impossible totals raise a protocol error rather than being misreported as successful completion

Limits and permissions

The preview REST API accepts at most 20 blobs per request and a maximum of 6 GB of uncompressed data. raw_sizes are validated and summed when all are known. Supplying sizes also avoids a metadata read by the ingestion service

The caller needs Kusto Table Ingestor permission on the target table and Database User access. Reading nonpublic source files additionally requires storage access through the authentication method in each storage connection string. delete_after_download = TRUE also requires delete permission and permanently removes successfully downloaded source blobs

References

Queued ingestion REST API (preview)

Queued ingestion status REST API (preview)

Supported ingestion formats

Storage connection strings

Data ingestion properties

Ingestion mappings and identity mapping

Examples

## Not run: 
# Discover the KQL database and a Lakehouse containing staged CSV files
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
files <- fabric_onelake_list(
  workspace,
  lakehouse,
  path = "Files/events"
)
csv_file <- files[grepl("[.]csv$", files$path), ][1L, ]

# Build the source URI from discovered IDs and the listed file path
source <- paste0(
  "https://onelake.dfs.fabric.microsoft.com/",
  workspace$id, "/", lakehouse$id, "/", csv_file$path[[1L]],
  ";impersonate"
)

# A named mapping is optional when the source matches the table schema
table <- Sys.getenv("FABRIC_KQL_TABLE")
mapping <- Sys.getenv("FABRIC_KQL_CSV_MAPPING", unset = "")

# Queue the file once using a stable ingest-if-not-exists key
ingestion <- fabric_kql_ingest(
  database,
  table = table,
  sources = source,
  format = "csv",
  mapping = if (nzchar(mapping)) mapping else NULL,
  ignore_first_record = TRUE,
  ingest_if_not_exists = paste0("file:", csv_file$path[[1L]])
)

# Wait for every submitted file to reach a terminal ingestion state
result <- fabric_kql_ingestion_status(
  ingestion,
  wait = TRUE,
  timeout = 900
)
result$state
result$details

## End(Not run)

Run a KQL query in Microsoft Fabric

Description

Runs a read-only query against a KQL database and returns the result as a tibble. KQL databases are commonly used for event, log, telemetry, and time-series data in a Fabric Eventhouse

Usage

fabric_kql_query(
  cluster,
  query,
  database = NULL,
  parameters = list(),
  request_properties = list(),
  timeout = 60,
  retain_raw_frames = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list()
)

Arguments

Value

A typed tibble for one primary result, a fabric_kql_tables list for multiple primary results (one named element per table), or an empty tibble when there is no primary result. See Details for the KQL-to-R type mapping

Basic use

The easiest input is an item from fabric_kql_databases(), which already contains the database name and its Query URI. If you copy a URI from Fabric, choose Query URI, not Ingestion URI. This function reads existing data; it does not load data or run management commands

Put changing values in parameters and declare them in KQL with ⁠declare query_parameters(...)⁠. The values are sent separately from the query text, which is safer and easier to quote correctly than using paste(). Scalar R values become KQL scalar values; vectors and lists become dynamic arrays or objects. Nested date/time objects and non-finite numbers are rejected because JSON conversion can change their values or types. Use explicit strings (including timezone and fractional seconds for timestamps) and cast them in KQL, or pass these values as separate scalar parameters

Advanced request options

request_properties controls server behavior such as timeouts and result truncation. Most users can leave it empty Microsoft Fabric does not support the queryconsistency or query_weakconsistency_session_id request properties. Do not include either name in request_properties, even though Azure Data Explorer supports them

Result types

KQL bool, datetime, int, long, real, and timespan columns normally become logical, UTC POSIXct, integer, bit64::integer64, double, and difftime vectors. Base R and 'bit64' reserve the minimum signed int and long values for missing data; a column containing either boundary is returned as character with a warning so the value remains exact. dynamic columns are list-columns, and GUIDs, strings, and decimal values are character vectors. Keeping decimal values in their original lexical form avoids the silent precision loss that conversion to an R double can cause

A query with several result tables returns a named fabric_kql_tables list; a query with no result table returns an empty tibble. Service metadata is retained in ⁠kusto_*⁠ attributes for troubleshooting

Permissions

The caller needs database access through a Fabric workspace role, Eventhouse sharing, or KQL database sharing. Authentication uses the Kusto query service

References

Access a KQL database and copy its Query URI

Kusto query HTTP request and parameters

Kusto request properties

Kusto role-based access control

Examples

## Not run: 
# Discover the KQL database and choose one of its existing tables
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]
table <- Sys.getenv("FABRIC_KQL_TABLE")

# Keep the changing table name out of the KQL text by using a parameter
events <- fabric_kql_query(
  database,
  query = paste(
    "declare query_parameters(selected_table:string);",
    "table(selected_table) | take 100"
  ),
  parameters = list(selected_table = table)
)

## End(Not run)

Read a Microsoft Fabric KQL table

Description

Provides the table-oriented read counterpart to fabric_kql_write_table(). It safely resolves the table through Kusto's table() function, optionally projects columns and limits rows, then delegates typed result handling to fabric_kql_query(). Use that lower-level function for filters, ordering, joins, aggregations, or other KQL expressions.

Usage

fabric_kql_read_table(
  cluster,
  table,
  database = NULL,
  columns = NULL,
  limit = NULL,
  request_properties = list(),
  timeout = 60,
  retain_raw_frames = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list()
)

Arguments

Value

A typed tibble containing the selected table rows. Kusto metadata is retained in the same attributes as fabric_kql_query().

Large results

The Kusto query HTTP response is collected and decoded in R. Use columns and limit to bound an interactive read. For a result too large for client memory, use fabric_kql_export() to export it server-side to OneLake or another supported storage destination.

References

Kusto table() function

Kusto take operator

Kusto entity names

Kusto query HTTP request

Examples

## Not run: 
# Discover a KQL database instead of copying its Query URI and name
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]

# Choose an existing table shown under Tables in the Fabric KQL explorer
table <- Sys.getenv("FABRIC_KQL_TABLE")

# Read a bounded portion of that table into a tibble
events <- fabric_kql_read_table(
  database,
  table,
  limit = 1000
)

## End(Not run)

Discover Microsoft Fabric KQL tables

Description

Lists tables in a Fabric KQL database through Kusto's management endpoint. With detail = TRUE, retrieves the database JSON schema once and exposes each table's ordered columns while retaining its complete metadata.

Usage

fabric_kql_tables(
  cluster,
  database = NULL,
  detail = TRUE,
  timeout = 60,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list()
)

Arguments

Value

A tibble with table name, database, folder, description, list-column columns, parsed schema_metadata, and the unmodified listing row in raw.

References

Kusto ⁠.show tables⁠ command

Kusto ⁠.show database schema⁠ command

Examples

## Not run: 
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]

tables <- fabric_kql_tables(database)
events <- fabric_kql_read_table(database, tables[1L, ], limit = 1000)

## End(Not run)

Write an R or Arrow object to an Eventhouse table

Description

Serializes an R or Arrow object to Parquet, uploads it using the storage container or OneLake folder preferred by the Kusto ingestion service, submits tracked queued ingestion, waits for the terminal per-file result, and manages staging cleanup. With cleanup = TRUE, Storage sources may be deleted after download, before ingestion succeeds; OneLake staging is removed only after confirmed success. Use cleanup = FALSE to retain Storage sources for recovery.

Usage

fabric_kql_write_table(
  cluster,
  table,
  data,
  database = NULL,
  mapping = NULL,
  staging_folder = NULL,
  staging_root = "fabricqueryr-staging",
  cleanup = TRUE,
  keep_staging_on_failure = TRUE,
  compression = "snappy",
  target_file_size = 512 * 1024^2,
  max_rows_per_file = NULL,
  tags = character(),
  ingest_if_not_exists = character(),
  skip_batching = FALSE,
  creation_time = NULL,
  timeout = 900,
  poll_interval = 2,
  error_on_failure = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  storage_token = NULL,
  auth_args = list(),
  create_if_missing = FALSE,
  column_types = NULL,
  query_cluster = NULL,
  numeric_policy = c("exact", "service"),
  .sleep = Sys.sleep,
  .now = Sys.time
)

Arguments

Value

A fabric_kql_write_result containing row/file counts, compressed Parquet bytes/part_bytes, diagnostic Arrow buffer_bytes/part_buffer_bytes, normalized ingestion status, tracking handle, source IDs, and staging disposition.

One-call staging workflow

The queued-ingestion REST API accepts storage blobs rather than inline R values. This function provides the higher-level one-call workflow: it reads the ingestion service's preview configuration, honors its preferred upload method, creates a unique fabricqueryr-staging path, and uploads bounded Parquet parts. Service-provided Storage containers use their short-lived SAS credentials. OneLake staging uses a Storage-audience access token, so an audience-aware credential obtains both required tokens. When token is a fixed bearer token or AzureToken and OneLake is selected, supply the separate storage_token. staging_folder explicitly selects OneLake and overrides the advertised upload preference with a trusted ⁠Files/⁠ URI.

The caller therefore needs Kusto Table Ingestor and Database User access, plus write/delete access when OneLake is selected. Advertised Storage containers carry the service-managed SAS access needed for staging.

R and Arrow inputs

Data frames and tibbles are converted through Arrow. Factors become strings; complex and difftime columns require an explicit conversion. Arrow Tables, RecordBatches, Datasets, Scanners, arrow_dplyr_query objects, and RecordBatchReaders are accepted, as are Arrow-compatible nanoarrow_array_stream objects returned by package query helpers. Lazy inputs are read one record batch at a time and written directly to a temporary Parquet parts, so the complete data set is never collected into R memory. A supplied reader or stream is single-use and is consumed.

Parquet identity mapping matches source fields to existing KQL columns by case-sensitive name. Before staging, the writer verifies that those names and their Kusto scalar types exactly match the target table. Supply mapping when the Parquet schema and table need an explicit predefined mapping; a named mapping bypasses this identity-schema check.

ingest_if_not_exists requires staging to produce one Parquet file, regardless of skip_batching. A shared idempotency tag can suppress later files in the same logical write. Stage one file or omit the idempotency key.

The service's advertised maxDataSize and source rawSize refer to the uncompressed source representation. Arrow's in-memory buffer size is not an equivalent Parquet measurement, so the writer deliberately omits rawSize and lets Kusto inspect the staged Parquet metadata. Compressed file sizes and Arrow buffer sizes remain available separately in the result.

Set create_if_missing = TRUE to issue Kusto's idempotent ⁠.create table⁠ command after local validation and before upload. A missing table is created from the Arrow schema; an existing table is returned unchanged, so this option never alters an existing schema. Common Arrow scalar and nested types are inferred as Kusto types. Supply a named column_types vector to override every column type.

By default, decimal values are checked in every staged Parquet batch before table creation or upload. Kusto ingestion can replace decimals with more than 34 significant digits by null even when ingestion succeeds. Precision above 34 in an Arrow schema is allowed when the actual values fit; insignificant leading and trailing zeros do not count. The same check applies inside nested data and with explicit column_types or a named mapping. It does not certify arbitrary transformations in those user-selected mappings. Convert decimal columns explicitly to Arrow strings to transfer their full text, or select numeric_policy = "service" to accept service conversion, rounding and nulls. Kusto strings merge missing and empty values; preserve a separate null flag when that distinction matters. The check protects mathematical decimal values within the staged Parquet representation; Kusto can canonicalize their precision, scale and trailing-zero spelling.

Service-owned Storage credentials are reacquired after local serialization. During a multipart upload, the writer honors the advertised configuration refresh interval and retries once with new credentials when Storage reports an expired authorization.

Failure and cleanup safety

A successful tracked ingestion is cleaned up by default. Kusto removes service-owned Storage blobs after download; the client removes OneLake staging after confirmed success. Ambiguous results retain OneLake staging. With Storage and cleanup = TRUE, an ambiguous or failed batch reports staging_retained = NA: some or all blobs may already have been deleted. Set cleanup = FALSE to retain Storage sources for recovery. After a confirmed terminal failure, the client leaves remaining staging alone unless keep_staging_on_failure = FALSE. The full staging path is carried by fabric_kql_write_error conditions. A transport failure during OneLake's final atomic rename can also leave the unique destination present; upload errors report staging_retained = NA and the path to inspect.

References

Queued ingestion configuration REST API (preview)

Queued ingestion REST API (preview)

Create a Kusto table

Kusto scalar data types

Kusto Parquet mappings

OneLake ADLS-compatible access

Arrow RecordBatchReader

Arrow Parquet writer

Examples

## Not run: 
# Discover the KQL database that will receive the R data
workspace <- fabric_workspaces()[[1L]]
database <- fabric_kql_databases(workspace)[[1L]]

# Create a new table when needed, stage the data, and wait for ingestion
result <- fabric_kql_write_table(
  database,
  table = "EventsFromR",
  data = data.frame(id = 1:3, value = c("a", "b", "c")),
  create_if_missing = TRUE,
  ingest_if_not_exists = "r-batch-2026-08-14"
)
result$status$state

# A local Arrow Dataset is scanned batch by batch rather than collected
dataset <- arrow::open_dataset(Sys.getenv("ARROW_DATASET_PATH"))
fabric_kql_write_table(database, "EventsFromArrow", dataset)

## End(Not run)

Read a Microsoft Fabric Lakehouse table

Description

Provides the symmetric read counterpart to fabric_lakehouse_write_table(). It resolves a discovered Lakehouse object and table record, then delegates to the authenticated OneLake Delta reader. Use result = "arrow_stream" to keep a larger result out of R memory.

Usage

fabric_lakehouse_read_table(
  lakehouse,
  table,
  workspace = NULL,
  schema = NULL,
  columns = NULL,
  limit = NULL,
  version = NULL,
  result = c("tibble", "arrow_stream"),
  verbose = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com"
)

Arguments

Details

Direct reads use the Python runtime described in fabric_delta_config(). See fabric_onelake_read_delta_table() for runtime setup, supported Delta features, OneLake permissions, and column-type conversion rules.

Value

A tibble, or a disk-backed nanoarrow_array_stream when result = "arrow_stream". Explicit release deletes its temporary file.

References

OneLake table APIs for Delta

Connect to OneLake

Examples

## Not run: 
# Discover both the Lakehouse and the table to read
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
tables <- fabric_lakehouse_tables(lakehouse)
table <- tables[1L, ]

# Read the discovered table into a tibble
rows <- fabric_lakehouse_read_table(lakehouse, table)

# Count rows in batches when the full table may not fit in R memory
row_count <- local({
  stream <- fabric_lakehouse_read_table(
    lakehouse,
    table,
    result = "arrow_stream"
  )
  on.exit(nanoarrow::nanoarrow_pointer_release(stream), add = TRUE)
  reader <- arrow::as_record_batch_reader(stream)
  on.exit(reader$Close(), add = TRUE, after = FALSE)
  count <- 0
  repeat {
    batch <- reader$read_next_batch()
    if (is.null(batch)) break
    count <- count + batch$num_rows
  }
  count
})

## End(Not run)

Discover and load Microsoft Fabric Lakehouse tables

Description

Use Fabric's table APIs to inspect Delta tables, load staged CSV or Parquet files, or write an R/Arrow object through a failure-aware staging workflow.

• fabric_lakehouse_tables() combines Fabric's paginated List Tables API with the read-only OneLake Delta table API. The first supplies managed or external type, format, and location; the second supplies schemas and, with detail = TRUE, column metadata.

• fabric_lakehouse_load_table() starts the preview Fabric Load Table API for a file or folder that already exists below the Lakehouse ⁠Files/⁠ area. It returns a handle accepted by fabric_operation_status().

• fabric_lakehouse_write_table() streams an R or Arrow object to Parquet, uploads it to a unique ⁠Files/⁠ staging path, waits for the Delta load, and removes the staged file after confirmed success by default.

Usage

fabric_lakehouse_tables(
  lakehouse,
  workspace = NULL,
  schema = NULL,
  detail = TRUE,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_lakehouse_load_table(
  lakehouse,
  table,
  path,
  workspace = NULL,
  schema = NULL,
  path_type = c("File", "Folder"),
  format = NULL,
  mode = c("Overwrite", "Append"),
  recursive = FALSE,
  header = TRUE,
  delimiter = ",",
  file_extension = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base
)

fabric_lakehouse_write_table(
  lakehouse,
  table,
  data,
  workspace = NULL,
  schema = NULL,
  mode = c("Overwrite", "Append"),
  staging_root = "Files/fabricqueryr-staging",
  cleanup = TRUE,
  keep_staging_on_failure = TRUE,
  compression = "snappy",
  target_file_size = 512 * 1024^2,
  max_rows_per_file = NULL,
  poll_interval = NULL,
  timeout = 900,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  dfs_base = "https://onelake.dfs.fabric.microsoft.com",
  storage_token = NULL
)

Arguments

Value

fabric_lakehouse_tables() returns a tibble with table name, schema, full_name, type, format, location, timestamps, list-column columns, schema_metadata, the unmodified OneLake raw record, and the matching unmodified Fabric fabric_raw record. Unknown future metadata remains available in those raw list columns.

fabric_lakehouse_load_table() returns a reusable fabric_operation. Pass it to fabric_operation_status(), fabric_operation_wait(), or fabric_operation_result().

fabric_lakehouse_write_table() returns a fabric_lakehouse_write_result containing the destination, row count, terminal operation state, staging path, and whether staging was retained.

Preview status and permissions

Microsoft marks Fabric's List Tables and Load Table routes as preview or beta and does not recommend them for production use. Loading requires write access to the Lakehouse and the Lakehouse.ReadWrite.All delegated scope. Discovery requires Lakehouse.Read.All or Lakehouse.ReadWrite.All for the Fabric list plus table read permission for OneLake metadata.

Fabric currently rejects List Tables for some schema-enabled Lakehouses. In that documented-endpoint/service mismatch, discovery still returns OneLake schema, format, location, and column metadata; type can be missing because OneLake currently returns a null table type for those records.

Service principals and managed identities are supported by the Load Table API. Tenant and item permissions still determine whether those identities can use OneLake and the Lakehouse.

Choose an existing-file load or an R-object write

fabric_lakehouse_load_table() never uploads a local file or serializes an R object. Its path must already exist inside the selected Lakehouse's OneLake ⁠Files/⁠ area. Use fabric_onelake_upload() first when intentionally managing that source yourself, or use fabric_lakehouse_write_table() for a single call that accepts a data frame, tibble, or Arrow object, stages it, waits for the load, and cleans up.

Both load functions can create a missing destination Delta table. Fabric infers its schema from the source. No create_if_missing flag is needed.

Data types and names

Arrow determines the Parquet schema before Fabric infers the destination Delta schema. Ordinary R logical, integer, double, character, Date, POSIXct, and bit64::integer64 columns map to their corresponding Parquet logical types. Factors are written as strings. List columns are passed to Arrow as nested data and can fail if their values do not have one consistent Arrow type. R complex and difftime columns are rejected.

R has no native fixed-precision decimal vector. Supply Arrow data with a decimal field when decimal precision and scale must be explicit. Fabric's Load to Tables flow does not accept a caller-defined destination schema, so use Spark or another schema-controlled writer when inference is unsuitable.

To preserve names exactly, fabric_lakehouse_write_table() requires unique column names containing only Unicode letters, decimal digits, and underscores, up to Fabric's documented 128-character limit. Use precomposed letters: managed Parquet loads reject decomposed combining marks, connector punctuation other than underscore, and numeric symbols such as superscript digits.

Failure and cleanup behavior

The high-level writer uploads complete Parquet parts atomically to a unique folder and starts the managed folder load only after every upload succeeds. A successful load is a committed Delta operation. On failure, the destination is left to Fabric's transactional load behavior and 'fabricQueryR' never edits ⁠Tables/⁠ files.

Retained staging paths are included in fabric_lakehouse_write_error conditions so the source can be inspected or passed to fabric_lakehouse_load_table() again. Cleanup failures after a successful load produce a warning and return staging_retained = TRUE; they do not make a committed table load appear to have failed. Once Fabric accepts a load, staging is retained if status polling loses access or fails ambiguously; only a confirmed terminal operation failure permits failure cleanup.

References

OneLake table APIs for Delta

Getting started with OneLake Delta table APIs

Arrow RecordBatchReader

List Lakehouse tables

Load a Lakehouse table

Load a schema Lakehouse table (beta)

Load to Delta Lake tables

Examples

## Not run: 
# Discover a Lakehouse instead of copying its workspace and item IDs
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]

# List its existing Delta tables
tables <- fabric_lakehouse_tables(lakehouse)

# Discover a CSV already stored in this Lakehouse's Files area
files <- fabric_onelake_list(
  workspace,
  lakehouse,
  path = "Files/incoming"
)
csv_file <- files[grepl("[.]csv$", files$path), ][1L, ]

# Load that discovered CSV into a managed Delta table
operation <- fabric_lakehouse_load_table(
  lakehouse,
  table = "orders_from_csv",
  path = csv_file$path[[1L]],
  format = "Csv",
  header = TRUE,
  delimiter = ","
)
fabric_operation_wait(operation, timeout = 900)

# Or stage an R data frame and write it as a managed Delta table
result <- fabric_lakehouse_write_table(
  lakehouse,
  table = "orders_from_r",
  data = data.frame(id = 1:3, amount = c(10.5, NA, 30))
)
result$operation_status$status

## End(Not run)

Submit a Microsoft Fabric Livy batch job

Description

Runs a complete Python, R, or Java/Scala Spark application stored in OneLake or ADLS. Use this for repeatable scripts and unattended processing; use fabric_livy_session() when several interactive statements should share variables and Spark state

Usage

fabric_livy_batch_submit(
  livy_url,
  file,
  name = NULL,
  class_name = NULL,
  args = NULL,
  jars = NULL,
  files = NULL,
  py_files = NULL,
  archives = NULL,
  conf = NULL,
  environment_id = NULL,
  target_lakehouse_id = NULL,
  tags = NULL,
  driver_memory = NULL,
  driver_cores = NULL,
  executor_memory = NULL,
  executor_cores = NULL,
  num_executors = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  verbose = TRUE,
  wait = FALSE,
  timeout = 1200,
  poll_interval = 5,
  cancel_on_timeout = TRUE
)

Arguments

Value

A FabricLivyBatch 'R6' object. Inspect its ⁠$state⁠, call ⁠$result()⁠ for structured metadata and logs, and call ⁠$wait()⁠ later when submitting with wait = FALSE

Before you submit

Fabric needs a workspace on supported capacity and a Lakehouse. The application file must already be accessible through an ABFS/ABFSS URI; this function does not upload a local script. Use fabric_onelake_upload() first when needed

Python and Java batch applications have produced their expected output in the package's persistent Fabric sandbox. Standalone R batches remain unverified: attempts have failed during Spark-context initialization. Treat the R batch path as experimental and validate an application's output in the target runtime before relying on it. Successful kind = "sparkr" interactive statements do not establish standalone R batch support.

Delegated sign-in requires Lakehouse.Execute.All, Lakehouse.Read.All, Code.AccessFabric.All, and Code.AccessStorage.All. Add Code.AccessAzureKeyvault.All, Code.AccessAzureDataLake.All, Code.AccessAzureDataExplorer.All, or Code.AccessSQL.All only when Spark accesses that Azure service at runtime. The signed-in identity also needs an appropriate workspace role

Microsoft's current batch guide is internally inconsistent about service principals: its introduction says SPN is unsupported, while its authentication section provides a certificate-based SPN example. This package can acquire and send a client-credentials token, but cannot make the Fabric service accept that identity. Until Microsoft clarifies the contract, verify unattended batch authentication in the target tenant and use a delegated user when the service rejects an SPN. A Contributor role alone is not a guarantee of batch SPN support

See Also

Microsoft Fabric batch jobs

Examples

## Not run: 
# Discover the Lakehouse and Python file used by this batch
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]
scripts <- fabric_onelake_list(
  workspace,
  lakehouse,
  path = "Files/jobs"
)
script <- scripts[grepl("[.]py$", scripts$path), ][1L, ]
script_uri <- paste0(
  "abfss://", workspace$id, "@onelake.dfs.fabric.microsoft.com/",
  lakehouse$id, "/", script$path[[1L]]
)

# Submit the discovered script and wait for its Spark application to finish
batch <- fabric_livy_batch_submit(
  lakehouse,
  file = script_uri,
  wait = TRUE,
  cancel_on_timeout = TRUE
)
batch$result()

## End(Not run)

Run Spark code in a temporary Microsoft Fabric Livy session

Description

Starts Spark, runs one piece of code, returns its output, and closes the Spark session. This is the simplest Livy helper for a one-off operation. For quick reads from a Lakehouse or Warehouse, SQL is often faster to start

Usage

fabric_livy_query(
  livy_url,
  code,
  kind = c("spark", "pyspark", "sparkr", "sql"),
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  environment_id = NULL,
  conf = NULL,
  verbose = TRUE,
  poll_interval = 2,
  timeout = 600,
  ...
)

Arguments

Value

Invisibly, a fabric_livy_statement_result list. The most useful component is output$parsed: a tibble for tabular output, an R object for JSON, or a character vector for text. The result also keeps status, timing, submitted code, errors, and the original response. A successful statement is still returned when session cleanup fails, with a fabric_livy_cleanup_warning identifying the retained session. When both execution and cleanup fail, a fabric_livy_execution_cleanup_error retains the execution error and safe cleanup diagnostics

Tabular column names

Duplicate SQL aliases and joined column names are repaired with make.unique(names, sep = "..."): for example, ⁠id, id⁠ becomes ⁠id, id...1⁠. Every column retains its positional values. The spark_schema attribute keeps the original header names and types, and the result retains the original response.

Before you run code

Fabric needs a workspace on supported capacity, a Lakehouse, and the tenant admin setting for the Livy API enabled. In the Fabric portal, open the Lakehouse settings, find Livy endpoint, and copy the session-job connection string. For several statements that reuse variables and Spark state, use fabric_livy_session(). To run a complete Python, Scala/Java, or R application file, use fabric_livy_batch_submit()

A delegated caller needs the Lakehouse.Execute.All, Lakehouse.Read.All, Code.AccessFabric.All, and Code.AccessStorage.All scopes and must be a Contributor in the workspace. For session jobs, Microsoft's current guide also documents service-principal (SPN) tokens. The service principal must be added to the workspace as a Contributor, but that role alone does not override tenant settings or other service-side identity restrictions. Add Code.AccessAzureKeyvault.All, Code.AccessAzureDataLake.All, Code.AccessAzureDataExplorer.All, or Code.AccessSQL.All only when the Spark code accesses that Azure service at runtime

Spark long and decimal columns are returned as character values when needed to preserve them exactly. Dates and timestamps with a time zone use R temporal classes; timestamps without a time zone remain wall-clock text Fabric's SQL JSON output represents non-finite floating-point values as null, so those values are returned as typed missing values. Binary and nested values use list-columns Nested decimal values retain their JSON spelling. Fabric may round these values before sending SQL JSON output; cast decimal leaves to STRING in Spark when full precision is required across that service boundary. Generic JSON arrays combine compatible numbers into numeric vectors. Mixed scalar types remain lists or tibble list-columns so numbers and exact integer or decimal strings retain their original values.

R on Runtime 2.0

Microsoft Fabric distributes sparklyr and documents sparklyr::spark_connect(method = "synapse") for Fabric notebooks and Spark job definitions. Microsoft does not currently document that connection from an item-scoped Livy session, and this package's live suite validates the "sparkr" interpreter but not a sparklyr connection over it. Treat that adaptation as experimental and verify it in the target runtime before use. It still depends on the SparkR JVM bridge, which Spark 4.x deprecates. Prefer PySpark or Spark SQL when the remote workload must be independent of that bridge

See Also

Microsoft Fabric Livy API overview, Livy API setup and authorization, Use sparklyr in Fabric, and Fabric Runtime 2.0

Examples

# Livy can run SQL, PySpark, Spark, and SparkR code in Microsoft Fabric
# This function is not called automatically because it requires credentials
fabric_livy_query_example <- function() {
  # Discover a Lakehouse whose record contains its Fabric Livy endpoint
  workspace <- fabric_workspaces()[[1L]]
  lakehouse <- fabric_lakehouses(workspace)[[1L]]
  table <- fabric_lakehouse_tables(lakehouse)[1L, ]

  # Build SQL from the discovered table, then close the temporary session
  sql <- sprintf(
    "SELECT COUNT(*) AS row_count FROM `%s`.`%s`",
    table$schema[[1L]],
    table$name[[1L]]
  )
  sql_result <- fabric_livy_query(
    livy_url = lakehouse,
    kind = "sql",
    code = sql
  )

  # PySpark avoids the SparkR bridge. The Livy vignette separately labels the
  # item-scoped sparklyr adaptation experimental and not live-validated here
  pyspark_result <- fabric_livy_query(
    livy_url = lakehouse,
    kind = "pyspark",
    code = "print(1 + 2)"
  )

  invisible(list(sql = sql_result, pyspark = pyspark_result))
}

Create a Microsoft Fabric Livy session

Description

Starts Spark compute that can run several statements while keeping variables and Spark state between calls. Use fabric_livy_query() instead for a single, self-contained operation

Usage

fabric_livy_session(
  livy_url,
  high_concurrency = FALSE,
  session_tag = NULL,
  name = NULL,
  tags = NULL,
  conf = NULL,
  environment_id = NULL,
  archives = NULL,
  driver_memory = NULL,
  driver_cores = NULL,
  executor_memory = NULL,
  executor_cores = NULL,
  num_executors = NULL,
  artifact_name = NULL,
  file = NULL,
  class_name = NULL,
  args = NULL,
  jars = NULL,
  files = NULL,
  py_files = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  verbose = TRUE
)

Arguments

Value

A newly created FabricLivySession. It may still be starting; call ⁠$wait()⁠ before ⁠$submit()⁠/⁠$run()⁠, and ⁠$close()⁠ when finished. These handle lifecycle methods do not have separate free-function wrappers

Choosing a session type

Use a standard session for a typical sequence in one R process. High concurrency is for applications that run several independent Spark workloads at the same time; it is not needed for several sequential statements

Cleanup and permissions

No network request is made when an open object is garbage collected. Call ⁠$close()⁠ explicitly, and use on.exit(session$close()) inside functions Delegated sign-in requires Lakehouse.Execute.All, Lakehouse.Read.All, Code.AccessFabric.All, and Code.AccessStorage.All. Add Code.AccessAzureKeyvault.All, Code.AccessAzureDataLake.All, Code.AccessAzureDataExplorer.All, or Code.AccessSQL.All only when Spark accesses that Azure service at runtime. Microsoft's current session guide documents delegated-user and service-principal (SPN) tokens. The signed-in identity also needs an appropriate workspace role, and service-side tenant settings still apply

Timeouts

A fabric_livy_timeout_error contains the exact session or statement object in its handle field, so it can be polled or cancelled in the current R process. The kind-specific session or statement field contains safe, serializable metadata; a serialized handle intentionally loses its in-process credential

See Also

Microsoft session jobs, high-concurrency Livy, and the Apache Livy REST API

Examples

## Not run: 
# Discover the Lakehouse whose Livy endpoint will host the Spark session
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]

run_shared_state <- function(lakehouse) {
  # Keep one session alive so successive statements share Spark state
  session <- fabric_livy_session(lakehouse)
  on.exit(session$close(), add = TRUE)
  session$wait()
  session$run("shared_value = 40", kind = "pyspark")
  session$run("print(shared_value + 2)", kind = "pyspark")
}
run_shared_state(lakehouse)

run_high_concurrency <- function(lakehouse) {
  # A session tag lets compatible callers reuse high-concurrency compute
  session <- fabric_livy_session(
    lakehouse,
    high_concurrency = TRUE,
    session_tag = "report-workers"
  )
  on.exit(session$close(), add = TRUE)
  session$wait()
  session$run("SELECT current_timestamp()", kind = "sql")
}
run_high_concurrency(lakehouse)

## End(Not run)

Discover and reattach to Microsoft Fabric Livy work

Description

Lists existing Livy sessions or batches and creates a newly authenticated handle for work that was started by an earlier R process. Listing never returns authentication credentials. Attaching retrieves current service state and does not create a new session or batch.

Usage

fabric_livy_sessions(
  livy_url,
  high_concurrency = FALSE,
  top = 100L,
  skip = 0L,
  count = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL
)

fabric_livy_batches(
  livy_url,
  top = 100L,
  skip = 0L,
  count = TRUE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL
)

fabric_livy_session_attach(
  livy_url,
  session_id,
  high_concurrency = FALSE,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  verbose = TRUE
)

fabric_livy_batch_attach(
  livy_url,
  batch_id,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  audience = NULL,
  verbose = TRUE
)

Arguments

Value

fabric_livy_sessions() and fabric_livy_batches() return one page as a tibble with columns id, name, state, result, app_id, service timestamps, and raw. The tibble has total_count, page_size, and skip attributes. The attach functions return a FabricLivySession or FabricLivyBatch with a fresh in-process credential.

Restart recovery

Livy handles intentionally do not serialize their credentials. Store the service ID, then call the corresponding attach function after restarting R. Attaching only reconstructs the local handle; it never submits new Spark work.

High-concurrency recovery

Fabric supports acquiring an HC session and getting or deleting one by its HC session ID, but it does not expose a collection GET for highConcurrencySessions. Store the ID returned by fabric_livy_session() and pass it to fabric_livy_session_attach() with high_concurrency = TRUE. Calling fabric_livy_sessions() with high_concurrency = TRUE fails locally instead of sending an unsupported request.

See Also

Microsoft Fabric Livy API specification and Microsoft's high-concurrency endpoint reference

Examples

## Not run: 
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]

sessions <- fabric_livy_sessions(lakehouse)
session <- fabric_livy_session_attach(lakehouse, sessions$id[[1L]])
session$status()

batches <- fabric_livy_batches(lakehouse)
batch <- fabric_livy_batch_attach(lakehouse, batches$id[[1L]])
batch$status()

## End(Not run)

Work with Microsoft Fabric mirrored database tables

Description

Discover schemas and Delta tables replicated into a Fabric mirrored database, retrieve one table's detailed metadata, or read a table directly from OneLake. The discovery helpers use the read-only OneLake table metadata API; the reader uses the mirrored Delta log.

Usage

fabric_mirrored_database_schemas(
  mirrored_database,
  workspace = NULL,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_mirrored_database_tables(
  mirrored_database,
  workspace = NULL,
  schema = NULL,
  detail = TRUE,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_mirrored_database_table(
  mirrored_database,
  table,
  workspace = NULL,
  schema = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_mirrored_database_read_table(
  mirrored_database,
  table,
  workspace = NULL,
  schema = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  version = NULL,
  verbose = TRUE,
  dfs_base = "https://onelake.dfs.fabric.microsoft.com",
  columns = NULL,
  limit = NULL,
  result = c("tibble", "arrow_stream"),
  api_base = .fabric_api_base,
  storage_token = NULL
)

Arguments

Value

fabric_mirrored_database_schemas() returns the same schema tibble as fabric_lakehouse_schemas(). The table metadata functions return the same table tibble as fabric_warehouse_tables(). The reader returns a tibble or a single-use nanoarrow_array_stream.

SQL alternative

Mirrored databases also expose a read-only SQL analytics endpoint. Pass a discovered mirrored database object to fabric_sql_tables(), fabric_sql_read_table(), or fabric_sql_query() when SQL permissions or SQL views are required.

References

Get Mirrored Database

Mirroring in Microsoft Fabric

OneLake catalog table APIs

Examples

## Not run: 
workspace <- fabric_workspaces()[[1L]]
database <- fabric_mirrored_databases(workspace)[[1L]]

schemas <- fabric_mirrored_database_schemas(database)
tables <- fabric_mirrored_database_tables(database)
rows <- fabric_mirrored_database_read_table(database, tables[1L, ], limit = 1000)

## End(Not run)

Discover OneLake schemas and individual tables

Description

These helpers expose the read-only OneLake Delta table metadata API for Lakehouses and Warehouses. The schema helpers follow every metadata page. The singular table helpers retrieve one table's full column metadata without listing every table in every schema.

Usage

fabric_lakehouse_schemas(
  lakehouse,
  workspace = NULL,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_warehouse_schemas(
  warehouse,
  workspace = NULL,
  page_size = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

fabric_lakehouse_table(
  lakehouse,
  table,
  workspace = NULL,
  schema = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL,
  enrich_fabric = FALSE
)

fabric_warehouse_table(
  warehouse,
  table,
  workspace = NULL,
  schema = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  api_base = .fabric_api_base,
  table_api_base = .fabric_onelake_table_base,
  storage_token = NULL
)

Arguments

Value

The schema functions return a tibble with name, catalog, full_name, comment, owner, schema_id, timestamps, and the unmodified metadata record in raw. The table functions return one row with the same columns as fabric_lakehouse_tables() or fabric_warehouse_tables().

Permissions

The OneLake table API uses the Azure Storage token audience and requires permission to read the item's tables through OneLake.

References

Explore tables with OneLake catalog APIs

OneLake table APIs for Delta

Examples

## Not run: 
workspace <- fabric_workspaces()[[1L]]
lakehouse <- fabric_lakehouses(workspace)[[1L]]

schemas <- fabric_lakehouse_schemas(lakehouse)
orders <- fabric_lakehouse_table(lakehouse, "orders", schema = "dbo")

## End(Not run)

Work with files in Microsoft Fabric OneLake

Description

List, inspect, download, upload, and delete ordinary files stored in OneLake These helpers are intended for files such as CSV, JSON, images, and model artifacts in a Fabric item's ⁠Files/⁠ area

• fabric_onelake_list() lists paths and follows all continuation tokens

• fabric_onelake_metadata() returns file or directory properties

• fabric_onelake_download() reads a file into memory or streams it to disk

• fabric_onelake_upload() creates or replaces a file

• fabric_onelake_delete() explicitly deletes a file or directory

Usage

fabric_onelake_list(
  workspace,
  item = NULL,
  path = "",
  recursive = FALSE,
  page_size = 5000L,
  begin_from = NULL,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com"
)

fabric_onelake_metadata(
  workspace,
  item = NULL,
  path = "",
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com"
)

fabric_onelake_download(
  workspace,
  item = NULL,
  path = "",
  dest = NULL,
  range = NULL,
  overwrite = FALSE,
  if_match = NULL,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com"
)

fabric_onelake_upload(
  workspace,
  item = NULL,
  path = "",
  source,
  overwrite = FALSE,
  if_match = NULL,
  content_type = NULL,
  create_parents = TRUE,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com",
  allow_managed_tables = FALSE,
  chunk_size = getOption("fabricqueryr.onelake.chunk_size", 8 * 1024^2)
)

fabric_onelake_delete(
  workspace,
  item = NULL,
  path = "",
  recursive = FALSE,
  confirm = FALSE,
  if_match = NULL,
  item_type = NULL,
  tenant_id = Sys.getenv("FABRICQUERYR_TENANT_ID"),
  client_id = Sys.getenv("FABRICQUERYR_CLIENT_ID", unset =
    "04b07795-8ddb-461a-bbee-02f9e1bf7b46"),
  token = NULL,
  auth_args = list(),
  dfs_base = "https://onelake.dfs.fabric.microsoft.com",
  allow_managed_tables = FALSE
)

Arguments

Value

fabric_onelake_list() returns one row per path, including its item-relative path, file name, is_directory, content_length, etag, and modification/permission fields fabric_onelake_metadata() and fabric_onelake_upload() return a one-row tibble with the resolved path and available HTTP metadata fabric_onelake_download() returns a raw vector when dest = NULL, or invisibly returns the destination path after writing to disk fabric_onelake_delete() invisibly returns TRUE

Choosing a target

The easiest inputs are a workspace plus an item returned by fabric_lakehouses(). You can also use names, IDs, or a complete OneLake HTTPS/ABFSS path. When using an item name, include its type suffix, such as "Sales.Lakehouse", or supply item_type

A Lakehouse's ⁠Tables/⁠ area is managed as Delta tables. Use fabric_onelake_read_delta_table() to read those tables, and use SQL, Spark, or another Delta-aware tool to change them. Uploading or deleting individual files below ⁠Tables/⁠ can damage a table and is blocked by default

Permissions

The signed-in user or application needs access through a workspace role or the item's OneLake security roles, configured under Manage OneLake security. Uploading and deleting need write permission. Your Fabric administrator must also allow external apps to access OneLake. If a call returns HTTP 403 after sign-in succeeds, check both that tenant setting and the item's data permissions

Listing integrity

Directory listing validates every JSON page and path record before returning data. Malformed envelopes, invalid metadata values, and paths outside the requested item directory raise fabric_onelake_protocol_error; they are not silently converted to empty or partial results