Run a query against a Fabric GraphQL API — fabric_graphql

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

api: GraphQL endpoint, API ID, or one discovered GraphQLApi object. An item from fabric_graphql_apis() is usually easiest because it supplies the endpoint and workspace ID
query: One GraphQL document containing a query or mutation. Use variables for changing values instead of pasting values into this string
variables: Named list of values for variables declared in query. Numeric and other R missing values are sent as JSON null; numeric NaN and infinities are rejected because GraphQL JSON has no such numbers. Supply date-times as explicit ISO 8601 strings with a UTC Z or offset, for example "2024-02-29T12:34:56.123456Z". POSIXct and POSIXlt values are rejected, including inside nested inputs, because implicit JSON conversion can discard their time zone and fractional seconds. One-element values are normally sent as scalars. Wrap a one-element list variable in I(), for example list(ids = I("x")), to send it as an array
operation_name: Optional operation name. Supply it when the document contains more than one named operation; otherwise leave NULL
workspace_id: Workspace GUID. Required when api is a GraphQL API GUID, and otherwise inferred from a discovered object
error_policy: How GraphQL-level errors are handled. "return" lets the caller inspect partial data and errors; "warn" also makes errors visible immediately; "error" stops and attaches the result to a fabric_graphql_error. HTTP/authentication failures always stop
timeout: Maximum time in seconds for the request. The default allows Fabric's own 100-second query timeout response to arrive
idempotent: Logical. Permit retries after transient HTTP failures TRUE is normally suitable for a read-only query, but not for a mutation that could be applied twice
tenant_id: Microsoft Entra tenant ID. Defaults to FABRICQUERYR_TENANT_ID
client_id: Microsoft Entra application/client ID. Defaults to FABRICQUERYR_CLIENT_ID, with the Azure CLI application ID as fallback
token: Optional access token or token-provider function. Leave NULL to let 'fabricQueryR' use its normal sign-in flow for a Microsoft Fabric host. A custom API endpoint, including an API Management gateway, requires an explicitly supplied token or provider so an automatically acquired Fabric credential is not forwarded to another host
auth_args: Additional sign-in options passed to AzureAuth::get_azure_token()
audience: OAuth audience/scope passed to the credential. NULL selects the documented scope from the authentication flow. Set this only for a custom token provider or unusual identity flow
api_base: Fabric REST API base URL used to derive endpoints from IDs Most users should keep the default
numeric_policy: Numeric response policy. "exact" preserves decimal and exponent JSON numbers in GraphQL data as character source text; "double" decodes them as ordinary R doubles and can lose precision or lexical scale. Whole-number handling is unchanged

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

if (FALSE) { # \dontrun{
# 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
} # }