Skip to contents

Get started with 'fabricQueryR'

Source: vignettes/getting-started.Rmd
getting-started.Rmd

Microsoft Fabric is a collection of services for storing, transforming, and reporting on data. ‘fabricQueryR’ lets you work with many of those services from R: you can read Fabric data, send R data to Fabric, and start work that runs inside Fabric.

This guide introduces the basic Fabric concepts and completes one small read. Start here if you are new to either Fabric or ‘fabricQueryR’, then continue to a task-specific vignette.

The Fabric objects you will see

A workspace is a shared area that contains Fabric items. An item is a resource inside a workspace, such as a Lakehouse, Warehouse, semantic model, or notebook.

The most common data items have different purposes:

Item Think of it as A common R task
Lakehouse Files plus managed data tables Read or write a table or file
Warehouse A relational SQL database Query or load business tables
Eventhouse A database for event and time-series data Query with KQL or ingest events
Semantic model Report-ready tables, relationships, and calculations Query with DAX or refresh the model
API for GraphQL A structured API in front of Fabric data Request selected fields

OneLake is the storage layer shared by Fabric items. In a Lakehouse, the Files/ area contains ordinary files and the Tables/ area contains managed Delta tables. Delta is a storage format that supports efficient reads and writes, schema evolution, and transactional consistency.

Sign in

This guide uses APIs available in ‘fabricQueryR’ 1.0.0 and later. Install the package, load it, and set your organization’s Microsoft Entra tenant ID:

install.packages("fabricQueryR")

library(fabricQueryR)
Sys.setenv(FABRICQUERYR_TENANT_ID = "<your-tenant-id>")

The first Fabric call may open a browser. Sign in with the same work or school account that you use in the Fabric portal.

If your organization requires an approved application, your administrator may also give you a client ID to set as FABRICQUERYR_CLIENT_ID.

# Run this only when your administrator supplies a client ID:
Sys.setenv(FABRICQUERYR_CLIENT_ID = "<your-app-client-id>")

The authentication vignette explains this setup and the different ways to authenticate in more detail.

Find a workspace and an item

Start by listing the workspaces that your account can access:

# List all workspaces you can access
workspaces <- fabric_workspaces()

The result is a list of FabricWorkspace R6 objects. Each object keeps the workspace fields returned by Fabric and provides discovery methods. For example, $items() corresponds to fabric_items(), and $lakehouses() corresponds to fabric_lakehouses(). If the list is empty, check that your account has been granted access to a workspace in the Fabric portal. If the list is not empty, select a specific workspace:

# Select the first workspace in the list
workspace <- workspaces[[1L]]
workspace$displayName

For a script that will run repeatedly, selecting by exact name is more robust:

# Select a workspace by name
workspaces <- fabric_workspaces()
matches <- Filter(
  \(x) identical(x$displayName, "Analytics workspace"),
  workspaces
)
stopifnot(length(matches) == 1L)
workspace <- matches[[1L]]

Now list all items with $items() (fabric_items()), or ask directly for Lakehouses with $lakehouses() (fabric_lakehouses()):

# List all items in the workspace
items <- workspace$items()
items

# The generic interface also filters types without a typed convenience method
reports <- workspace$items(type = "Report")

# List only Lakehouses in the workspace
lakehouses <- workspace$lakehouses()
lakehouse <- lakehouses[[1L]]
lakehouse$displayName

A discovered item is a read-only R6 object. Read its Fabric metadata through fields such as $displayName, $type, and $id; methods matched to its type perform the useful next actions. For example, a FabricLakehouse provides $tables() (fabric_lakehouse_tables()), $read_table() (fabric_lakehouse_read_table()), and $write_table() (fabric_lakehouse_write_table()), plus OneLake, SQL, and Livy methods. Use $as_list() or as.list() only when another interface specifically requires a plain record. The typed workspace methods are an intentional convenience subset of Fabric’s larger item catalog. $items(type = ...) can discover other service types; those items retain all returned fields as generic FabricItem objects when the package has no workload-specific subclass.

Complete a first read

If the workspace contains a Lakehouse, reading one managed table is a simple first workflow. Use $tables() (fabric_lakehouse_tables()) to discover its tables and $read_table() (fabric_lakehouse_read_table()) to read one:

# List the tables in the Lakehouse
tables <- lakehouse$tables()
tables[c("schema", "name", "type")]

# Select the first table and read a small number of rows
first_table <- tables[1L, ]
rows <- lakehouse$read_table(
  first_table,
  limit = 100L
)

# Show the first few rows
head(rows)

The result is a tibble, which can be used with base R, ‘dplyr’, plotting packages, or other familiar R tools. limit = 100L keeps this first request small while you confirm that access and table selection are correct.

This direct Delta read uses Python through ‘reticulate’. The first read may download the required runtime and packages. Use fabric_delta_config() to inspect requirements, or fabric_delta_config(initialize = TRUE) to prepare the runtime before reading. Direct reads also need OneLake data access; use SQL or Spark if the table uses an unsupported Delta feature. The reading guide explains these choices.

Choose the next guide

There are often several valid ways to move the same data. The vignettes below compare the options and show how to use them. Continue with one of the following vignettes: