### Get and Start Databricks SQL Warehouse (R)

Source: https://databrickslabs.github.io/brickster/reference/get_and_start_warehouse

Retrieves information about a Databricks SQL warehouse and starts it if it's inactive. It then waits until the warehouse is active. This function relies on 'db_host()' and 'db_token()' for authentication and workspace URL.

```R
get_and_start_warehouse(
  id,
  polling_interval = 5,
  host = db_host(),
  token = db_token()
)
```

--------------------------------

### Start Warehouse API

Source: https://databrickslabs.github.io/brickster/reference/db_sql_warehouse_start

Starts a specified Databricks SQL warehouse.

```APIDOC
## POST /api/2.0/sql/warehouses/{}/start

### Description
Starts a specified Databricks SQL warehouse.

### Method
POST

### Endpoint
`/api/2.0/sql/warehouses/{warehouse_id}/start`

### Parameters
#### Path Parameters
- **warehouse_id** (string) - Required - The ID of the SQL warehouse to start.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this operation."
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the operation (e.g., "RUNNING").

#### Response Example
```json
{
  "example": {
    "status": "RUNNING"
  }
}
```
```

--------------------------------

### Install PyPI Package

Source: https://databrickslabs.github.io/brickster/reference/lib_pypi

Installs a specified PyPI package using the `lib_pypi` function. It takes the package name (optionally with a version) and an optional repository URL as input. If no repository is specified, the default pip index is used.

```r
lib_pypi(package = "simplejson", repo = NULL)
```

--------------------------------

### Example .Renviron with Multiple Profiles

Source: https://databrickslabs.github.io/brickster/articles/setup-auth

This is an example of an .Renviron file configured for the brickster package, supporting multiple Databricks connection profiles (default, dev, prod). Each profile uses the standard DATABRICKS_HOST, DATABRICKS_TOKEN, and DATABRICKS_WSID variables, with suffixes for non-default profiles.

```text
# default
DATABRICKS_HOST=xxxxxxx.cloud.databricks.com
DATABRICKS_TOKEN=dapixxxxxxxxxxxxxxxxxxxxxxxxx
DATABRICKS_WSID=123123123123123

# dev profile (example)
# DATABRICKS_HOST_DEV=dev.cloud.databricks.com
# DATABRICKS_TOKEN_DEV=dapidevxxxxxxxxxxxxxxxxxxxx

# prod profile (example)
# DATABRICKS_HOST_PROD=prod.cloud.databricks.com
# DATABRICKS_TOKEN_PROD=dapiprodxxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Install Library on Databricks Cluster (R)

Source: https://databrickslabs.github.io/brickster/reference/db_libs_install

Installs specified libraries onto a Databricks cluster. This function is asynchronous and will fail if the cluster is terminated. It supports various library types and handles dependencies. The installation order can be non-deterministic for older Databricks Runtimes unless a .wheelhouse.zip is used.

```R
db_libs_install(
  cluster_id,
  libraries,
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### Get and Start Warehouse

Source: https://databrickslabs.github.io/brickster/reference/get_and_start_warehouse

Retrieves information about a Databricks SQL warehouse. If the warehouse is inactive, it will be started and the function will wait until it is active.

```APIDOC
## GET /warehouses/{id}/start

### Description
Retrieves information about a Databricks SQL warehouse. If the warehouse is inactive, it will be started and the function will wait until it is active.

### Method
GET

### Endpoint
/warehouses/{id}/start

### Parameters
#### Path Parameters
- **id** (string) - Required - ID of the SQL warehouse.

#### Query Parameters
- **polling_interval** (integer) - Optional - Number of seconds to wait between status checks. Defaults to 5 seconds.
- **host** (string) - Optional - Databricks workspace URL. Defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token. Defaults to calling `db_token()`.

### Request Example
```json
{
  "id": "your_warehouse_id",
  "polling_interval": 5,
  "host": "https://your.databricks.host",
  "token": "your_databricks_token"
}
```

### Response
#### Success Response (200)
- **warehouse_info** (object) - Information about the SQL warehouse.

#### Response Example
```json
{
  "id": "your_warehouse_id",
  "name": "My SQL Warehouse",
  "state": "RUNNING",
  "cluster_size_bytes": 1073741824,
  "used_bytes": 0,
  "start_time": 1678886400000,
  "endpoint_url": "https://your.databricks.host/sql/endpoints/your_warehouse_id"
}
```
```

--------------------------------

### Start a Cluster

Source: https://databrickslabs.github.io/brickster/reference/db_cluster_start

Starts a terminated Databricks cluster given its canonical identifier.

```APIDOC
## POST /api/2.0/clusters/start

### Description
Start a terminated cluster given its ID. This is similar to `db_cluster_create()`, except the terminated cluster ID and attributes are preserved, and the cluster starts with the last specified cluster size. If the cluster is in the `RESTARTING` state, a `400` error is returned. You cannot start a cluster launched to run a job.

### Method
POST

### Endpoint
`/api/2.0/clusters/start`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cluster_id** (string) - Required - Canonical identifier for the cluster.
- **host** (string) - Optional - Databricks workspace URL, defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token, defaults to calling `db_token()`.
- **perform_request** (boolean) - Optional - If `TRUE` (default) the request is performed, if `FALSE` the httr2 request is returned _without_ being performed.

### Request Example
```json
{
  "cluster_id": "<your-cluster-id>",
  "host": "https://your-databricks-workspace.cloud.databricks.com",
  "token": "<your-databricks-token>"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the cluster start request was accepted.

#### Response Example
```json
{
  "message": "Accepted"
}
```

### Error Handling
- **400 Bad Request**: Returned if the cluster is in the `RESTARTING` state or if attempting to start a cluster launched to run a job.
- **404 Not Found**: Returned if the specified cluster ID does not exist.
```

--------------------------------

### Get All Repos API

Source: https://databrickslabs.github.io/brickster/reference/db_repo_get_all

Retrieves a list of all repositories accessible by the user, with options for filtering and pagination.

```APIDOC
## GET /api/2.0/repos

### Description
Retrieves a list of all repositories that the calling user has Manage permissions on. Results are paginated, with each page containing twenty repos. This endpoint can filter repositories by a path prefix and supports pagination using a next page token.

### Method
GET

### Endpoint
`/api/2.0/repos`

### Parameters
#### Query Parameters
- **path_prefix** (string) - Optional - Filters repos that have paths starting with the given path prefix.
- **next_page_token** (string) - Optional - Token used to get the next page of results. If not specified, returns the first page of results as well as a next page token if there are more results.

### Request Example
```json
{
  "path_prefix": "my_org/",
  "next_page_token": "some_token_string"
}
```

### Response
#### Success Response (200)
- **repos** (array) - A list of repository objects.
  - **id** (integer) - The ID of the repository.
  - **repo_id** (integer) - The ID of the repository.
  - **created_at** (string) - The timestamp when the repository was created.
  - **updated_at** (string) - The timestamp when the repository was last updated.
  - **url** (string) - The URL of the repository.
  - **path** (string) - The path of the repository.
  - **tag** (string) - The Git tag of the repository.
  - **branch** (string) - The Git branch of the repository.
  - **commit** (string) - The Git commit hash of the repository.
- **next_page_token** (string) - A token to retrieve the next page of results, if available.

#### Response Example
```json
{
  "repos": [
    {
      "id": 12345,
      "repo_id": 12345,
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z",
      "url": "https://github.com/databricks/notebooks.git",
      "path": "/Users/user@example.com/notebooks",
      "tag": null,
      "branch": "main",
      "commit": "abcdef1234567890"
    }
  ],
  "next_page_token": "next_token_string"
}
```
```

--------------------------------

### Get Status of All Libraries on All Clusters (R)

Source: https://databrickslabs.github.io/brickster/reference/db_libs_all_cluster_statuses

Retrieves the status of all libraries installed on Databricks clusters, including those configured for all clusters. It takes workspace host and token as arguments, with an option to perform the request or return the httr2 request object. Defaults to performing the request.

```r
db_libs_all_cluster_statuses(
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### Install Libraries on Databricks Cluster (R)

Source: https://databrickslabs.github.io/brickster/reference/libraries

This function allows specifying libraries to be installed on a Databricks cluster executing a task. It accepts various library types, including JARs, CRAN packages, Maven artifacts, PyPI packages, WHL files, and Egg files. Ensure the correct library specification format is used for successful installation.

```R
libraries(
  lib_jar("path/to/your.jar"),
  lib_cran("some_package"),
  lib_maven("com.example:artifact:1.0"),
  lib_pypi("another_package"),
  lib_whl("path/to/your.wheel.whl"),
  lib_egg("path/to/your.egg")
)
```

--------------------------------

### Install CRAN Package

Source: https://databrickslabs.github.io/brickster/reference/lib_cran

The `lib_cran` function installs a specified R package from a CRAN repository. It can use the default CRAN repository or a user-specified one.

```APIDOC
## Install CRAN Package

### Description
Installs an R package from a CRAN repository.

### Method
N/A (This is a function, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **package** (character) - The name of the CRAN package to install.
- **repo** (character, optional) - The repository where the package can be found. If not specified, the default CRAN repo is used.

### Request Example
```R
lib_cran(package = "dplyr")
lib_cran(package = "ggplot2", repo = "https://cloud.r-project.org/")
```

### Response
#### Success Response
N/A (Function execution)

#### Response Example
N/A
```

--------------------------------

### Start Databricks SQL Warehouse

Source: https://databrickslabs.github.io/brickster/reference/db_sql_warehouse_start

Starts a specified Databricks SQL warehouse. Requires the warehouse ID and optionally accepts host and token for authentication. The `perform_request` argument controls whether the API call is executed immediately or if the request object is returned. This function is part of the Warehouse API.

```r
db_sql_warehouse_start(
  id,
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### Wait for Library Installs on Databricks Cluster (R)

Source: https://databrickslabs.github.io/brickster/reference/wait_for_lib_installs

This R function, `wait_for_lib_installs`, polls the status of library installations on a specified Databricks cluster. It allows configuration of polling interval, error handling for failed installs, and authentication via workspace host and token. This is useful for ensuring all necessary dependencies are installed before proceeding with scripts.

```r
wait_for_lib_installs(
  cluster_id,
  polling_interval = 5,
  allow_failures = FALSE,
  host = db_host(),
  token = db_token()
)
```

--------------------------------

### Wait for Libraries to Install on Databricks Cluster

Source: https://databrickslabs.github.io/brickster/reference/wait_for_lib_installs

This function allows you to repeatedly check the installation status of libraries on a Databricks cluster, blocking script execution until dependencies are installed.

```APIDOC
## Wait for Libraries to Install on Databricks Cluster

### Description
Library installs on Databricks clusters are asynchronous. This function allows you to repeatedly check the installation status of each library. It can be used to block any scripts until required dependencies are installed.

### Method
GET

### Endpoint
`/libraries/wait_for_lib_installs`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **cluster_id** (string) - Required - Unique identifier of a Databricks cluster.
- **polling_interval** (integer) - Optional - Number of seconds to wait between status checks. Defaults to 5.
- **allow_failures** (boolean) - Optional - If `FALSE` (default) will error if any libraries status is `FAILED`. When `TRUE` any `FAILED` installs will be presented as a warning.
- **host** (string) - Optional - Databricks workspace URL, defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token, defaults to calling `db_token()`.

#### Request Body
None

### Request Example
```json
{
  "cluster_id": "your_cluster_id",
  "polling_interval": 10,
  "allow_failures": false
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of library installations (e.g., 'installed', 'failed', 'pending').

#### Response Example
```json
{
  "status": "installed"
}
```

### See Also
- `db_libs_cluster_status()`
```

--------------------------------

### Install Jar Library (Scala)

Source: https://databrickslabs.github.io/brickster/reference/lib_jar

Installs a JAR library on a Databricks cluster. Supports DBFS and S3 URIs for the JAR location. Ensure appropriate read access for S3 URIs, potentially requiring an instance profile for the cluster.

```r
lib_jar(jar)
```

--------------------------------

### Start Databricks REPL Session in R

Source: https://databrickslabs.github.io/brickster/articles/remote-repl

Initiates an interactive R session connected to a specified Databricks cluster. The REPL automatically checks and starts the cluster if it is inactive. The default language for the REPL is R.

```r
# start REPL
db_repl(cluster_id = "<insert cluster id>")
```

--------------------------------

### Start a Databricks Cluster

Source: https://databrickslabs.github.io/brickster/reference/db_cluster_start

Starts a terminated Databricks cluster given its ID. Preserves cluster attributes and size. Requires cluster ID and optionally workspace host and token. Can return the request object instead of performing it.

```r
db_cluster_start(
  cluster_id,
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### File Storage Information for Init Scripts

Source: https://databrickslabs.github.io/brickster/reference/init_script_info

Configures file storage information for init scripts. This is specifically available for clusters configured with Databricks Container Services. Refer to Databricks documentation for setup instructions.

```r
file_storage_info()
```

--------------------------------

### Install Libraries on Databricks Cluster

Source: https://databrickslabs.github.io/brickster/articles/cluster-management

Installs libraries on a Databricks cluster from various sources using `db_libs_install` and helper functions like `lib_cran`, `lib_pypi`, `lib_egg`, `lib_whl`, `lib_maven`, and `lib_jar`. This allows extending the functionality of a cluster by adding custom or specific packages.

```r
# Example for installing a CRAN package:
db_libs_install(libs = lib_cran(package = "dplyr"))

# Example for installing a PyPI package:
db_libs_install(libs = lib_pypi(package = "pandas"))

# Example for installing a JAR file:
db_libs_install(libs = lib_jar(path = "path/to/your/library.jar"))
```

--------------------------------

### Get Init Script Information

Source: https://databrickslabs.github.io/brickster/reference/init_script_info

Retrieves information about init scripts for Databricks clusters. This function is part of the data structures module and can accept multiple storage configuration instances.

```r
init_script_info(...)
```

--------------------------------

### Install Python Wheel Library using lib_whl (Python)

Source: https://databrickslabs.github.io/brickster/reference/lib_whl

The `lib_whl` function installs Python wheel libraries on a Databricks cluster. It accepts a URI pointing to the wheel file, supporting both DBFS and S3 paths. For S3, ensure the cluster has read access and follow specific naming conventions for zipped wheels.

```python
lib_whl(whl)
```

--------------------------------

### Get and Start Cluster

Source: https://databrickslabs.github.io/brickster/reference/get_and_start_cluster

Retrieves information about a Databricks cluster. If the cluster is inactive, it will be started and the function will wait until the cluster is active.

```APIDOC
## Get and Start Cluster

### Description
Retrieves information about a Databricks cluster. If the cluster is inactive, it will be started and the function will wait until the cluster is active.

### Method
GET (Implicit - operates on existing cluster)

### Endpoint
`/clusters/{cluster_id}` (Conceptual - actual interaction via R function)

### Parameters
#### Path Parameters
- **cluster_id** (string) - Required - Canonical identifier for the cluster.

#### Query Parameters
- **polling_interval** (integer) - Optional - Number of seconds to wait between status checks (default: 5).
- **host** (string) - Optional - Databricks workspace URL (defaults to `db_host()`).
- **token** (string) - Optional - Databricks workspace token (defaults to `db_token()`).
- **silent** (boolean) - Optional - If TRUE, suppresses progress messages (default: FALSE).

### Request Example
```R
get_and_start_cluster(
  cluster_id = "your_cluster_id",
  polling_interval = 10,
  silent = TRUE
)
```

### Response
#### Success Response (200)
- **cluster_info** (object) - Information about the cluster (as returned by `db_cluster_get()`).

#### Response Example
```json
{
  "cluster_id": "your_cluster_id",
  "state": "RUNNING",
  "cluster_name": "Example Cluster",
  "node_type_id": "Standard_DS3_v2",
  "autoscale": {
    "min_workers": 1,
    "max_workers": 4
  },
  "spark_version": "10.4.x-scala2.12",
  "aws_attributes": {
    "availability": "SPOT_WITH_FALLBACK",
    "zone_id": "us-west-2a"
  }
}
```
```

--------------------------------

### Connect to a Listed Lakebase Instance (R)

Source: https://databrickslabs.github.io/brickster/reference/db_lakebase_list

This example demonstrates how to connect to a Databricks lakebase instance after listing available instances using `db_lakebase_list`. It shows how to generate credentials using `db_lakebase_creds_generate` and then establish a connection using the `RPostgres` package with the obtained host, user, password (token), and database name. Finally, it lists tables within the connected database.

```r
library(brickster)
library(DBI)
library(RPostgres)

# list all lakebase instances
dbs <- db_lakebase_list()

# connect to the first instance available using {RPostgres}
# using identity that brickster is running as generate a token
creds <- db_lakebase_creds_generate(instance_names = dbs[[1]]$name)

con <- dbConnect(
  drv = RPostgres::Postgres(),
  host = dbs[[1]]$read_write_dns,
  user = db_current_user()$userName,
  password = creds$token,
  dbname = "databricks_postgres",
  sslmode = "require"
)

dbListTables(con)
```

--------------------------------

### Get and Start Databricks Cluster (R)

Source: https://databrickslabs.github.io/brickster/reference/get_and_start_cluster

Retrieves information about a Databricks cluster. If the cluster is inactive, it will be started and the function will wait until the cluster is active. It uses the Databricks API for cluster operations. Arguments include cluster_id, polling_interval, host, token, and a silent flag.

```R
get_and_start_cluster(
  cluster_id,
  polling_interval = 5,
  host = db_host(),
  token = db_token(),
  silent = FALSE
)
```

--------------------------------

### Databricks Cluster Configuration - R Example

Source: https://databrickslabs.github.io/brickster/reference/db_cluster_edit

Demonstrates how to configure a Databricks cluster using R. It specifies various parameters such as cluster ID, Spark version, node type, number of workers, autoscaling, naming, Spark configurations, cloud attributes, custom tags, initialization scripts, environment variables, autotermination, logging, SSH public keys, instance pool IDs, idempotency token, elastic disk, local disk encryption, Docker image, policy ID, data security mode, host, and token. This example assumes the availability of helper functions like `db_cluster_runtime_versions()`, `db_cluster_list_node_types()`, `cluster_autoscale()`, `aws_attributes()`, `cluster_log_conf()`, and `docker_image()`.

```r
cluster_config <- list(
  cluster_id = "<your_cluster_id>",
  spark_version = "12.2.x-scala2.12",
  node_type_id = "Standard_DS3_v2",
  num_workers = 5,
  autoscale = cluster_autoscale(min_workers = 2, max_workers = 10),
  name = "My Awesome Cluster",
  spark_conf = list(
    "spark.speculation" = TRUE,
    "spark.streaming.ui.retainedBatches" = 5
  ),
  cloud_attrs = aws_attributes(),
  driver_node_type_id = "Standard_DS4_v2",
  custom_tags = list(
    "team" = "data-science",
    "project" = "alpha"
  ),
  init_scripts = list(init_script_info( "dbfs:/path/to/init-script.sh" )),
  spark_env_vars = list(
    "SPARK_DAEMON_JAVA_OPTS" = "$SPARK_DAEMON_JAVA_OPTS -Dspark.shuffle.service.enabled=true"
  ),
  autotermination_minutes = 120,
  log_conf = cluster_log_conf(destination = "dbfs:/cluster-logs/"),
  ssh_public_keys = list("ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDO..."),
  driver_instance_pool_id = "<your_driver_instance_pool_id>",
  instance_pool_id = "<your_instance_pool_id>",
  idempotency_token = "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  enable_elastic_disk = TRUE,
  apply_policy_default_values = TRUE,
  enable_local_disk_encryption = TRUE,
  docker_image = docker_image(image = "databricks/spark:latest", "/usr/bin/env bash", "-c", "echo hello"),
  policy_id = "<your_policy_id>",
  kind = "jobs",
  data_security_mode = "LEGACY",
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)

```

--------------------------------

### Get Cluster Library Status with R

Source: https://databrickslabs.github.io/brickster/reference/db_libs_cluster_status

Retrieves the installation status of all libraries on a specified Databricks cluster. It allows specifying the cluster ID, Databricks host, and authentication token. The `perform_request` argument controls whether the API call is executed immediately or if the request object is returned.

```r
db_libs_cluster_status(
  cluster_id,
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### Database Instance API

Source: https://databrickslabs.github.io/brickster/reference/db_lakebase_get

Endpoints for managing database instances within Databricks.

```APIDOC
## GET /api/2.0/sql/warehouses/{id}

### Description
Retrieves a specific database instance by its name.

### Method
GET

### Endpoint
`/api/2.0/sql/warehouses/{name}`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the database instance to retrieve.

#### Query Parameters
- **host** (string) - Optional - The Databricks workspace URL. Defaults to `db_host()`.
- **token** (string) - Optional - The Databricks workspace token. Defaults to `db_token()`.
- **perform_request** (boolean) - Optional - If `TRUE` (default), the request is performed. If `FALSE`, the httr2 request is returned without being performed.

### Request Example
```json
{
  "name": "my_database_instance",
  "host": "https://my-databricks-workspace.cloud.databricks.com",
  "token": "dapi...",
  "perform_request": true
}
```

### Response
#### Success Response (200)
- **List** (list) - A list containing details of the database instance.

#### Response Example
```json
{
  "instance_details": {
    "name": "my_database_instance",
    "id": "xyz789",
    "status": "RUNNING"
  }
}
```
```

--------------------------------

### Check Library Installation Status on Databricks Cluster

Source: https://databrickslabs.github.io/brickster/articles/cluster-management

Retrieves the installation status of libraries for a specific Databricks cluster. This function is used to monitor the progress of library installations and uninstallation.

```r
db_libs_cluster_status(cluster_id = new_cluster$cluster_id)
```

--------------------------------

### Create Docker Image Connection

Source: https://databrickslabs.github.io/brickster/reference/docker_image

Establishes a connection to a Docker image using basic authentication. It is strongly recommended to use environment variables for credentials rather than storing them directly in scripts.

```r
docker_image(url, username, password)
```

--------------------------------

### Connect to Databricks Workspace with brickster

Source: https://databrickslabs.github.io/brickster/index

Demonstrates how to set up an R session to connect to a Databricks workspace. It requires setting the DATABRICKS_HOST environment variable and uses the open_workspace() function to view Databricks resources in the RStudio Connections Pane. It also shows how to list SQL warehouses.

```r
library(brickster)

# only requires `DATABRICKS_HOST` if using OAuth U2M
# first request will open browser window to login
Sys.setenv(DATABRICKS_HOST = "https://<workspace-prefix>.cloud.databricks.com")

# open RStudio/Positron connection pane to view Databricks resources
open_workspace()

# list all SQL warehouses
warehouses <- db_sql_warehouse_list()
```

--------------------------------

### Install CRAN Packages on Databricks Cluster

Source: https://databrickslabs.github.io/brickster/articles/cluster-management

Installs specified R packages from CRAN onto a Databricks cluster. It requires the cluster ID and a list of CRAN libraries. Installation is asynchronous.

```r
db_libs_install(
  cluster_id = new_cluster$cluster_id,
  libraries = libraries(
    lib_cran(package = "palmerpenguins"),
    lib_cran(package = "dplyr")
  )
)
```

--------------------------------

### List Database Instances

Source: https://databrickslabs.github.io/brickster/reference/db_lakebase_list

Retrieves a list of available database instances within a Databricks workspace. Supports pagination and allows for returning the raw request object.

```APIDOC
## List Database Instances

### Description
Retrieves a list of available database instances within a Databricks workspace. Supports pagination and allows for returning the raw request object.

### Method
GET

### Endpoint
/api/2.0/sql/warehouses

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Maximum number of instances to return in a single page. Defaults to 50.
- **page_token** (string) - Optional - Pagination token to retrieve the next page of results.

#### Request Body
None

### Request Example
```json
{
  "page_size": 50,
  "page_token": null
}
```

### Response
#### Success Response (200)
- **instances** (array) - A list of database instance objects.
  - **name** (string) - The name of the instance.
  - **read_write_dns** (string) - The read-write DNS address for the instance.

#### Response Example
```json
{
  "instances": [
    {
      "name": "my-db-instance",
      "read_write_dns": "my-db-instance.cloud.databricks.com"
    }
  ]
}
```
```

--------------------------------

### List SQL Queries

Source: https://databrickslabs.github.io/brickster/reference/db_query_list

Retrieves a list of SQL queries accessible to the user, ordered by creation time. Be aware of potential rate limiting if calling this API frequently.

```APIDOC
## GET /api/2.0/sql/queries

### Description
Retrieves a list of SQL queries accessible to the user, ordered by creation time.

### Method
GET

### Endpoint
/api/2.0/sql/queries

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Number of results to return for each request. Defaults to 20.
- **page_token** (string) - Optional - Token used to get the next page of results. If not specified, returns the first page of results as well as a next page token if there are more results.

### Request Example
```json
{
  "page_size": 20,
  "page_token": null
}
```

### Response
#### Success Response (200)
- **queries** (array) - A list of SQL queries.
  - **query_id** (string) - The ID of the query.
  - **query_name** (string) - The name of the query.
  - **creation_timestamp** (integer) - The creation timestamp of the query.
  - **last_modified_timestamp** (integer) - The last modified timestamp of the query.
- **next_page_token** (string) - A token to retrieve the next page of results, if available.

#### Response Example
```json
{
  "queries": [
    {
      "query_id": "123e4567-e89b-12d3-a456-426614174000",
      "query_name": "Example Query",
      "creation_timestamp": 1678886400000,
      "last_modified_timestamp": 1678886400000
    }
  ],
  "next_page_token": "some_token"
}
```
```

--------------------------------

### Install brickster R Package

Source: https://databrickslabs.github.io/brickster/index

Shows the R command to install the brickster package from CRAN. It also includes commented-out code for installing the development version using the 'pak' package manager.

```r
install.packages("brickster")
```

```r
# install.packages("pak")
pak::pak("databrickslabs/brickster")
```

--------------------------------

### Get Schema (Unity Catalog)

Source: https://databrickslabs.github.io/brickster/reference/db_uc_schemas_get

Retrieves schema information from Databricks Unity Catalog.

```APIDOC
## Get Schema (Unity Catalog)

### Description
Retrieves schema information from Databricks Unity Catalog, allowing you to fetch details about a specific schema within a catalog.

### Method
GET

### Endpoint
`/api/2.0/unity-catalog/schemas/{catalog}/{schema}`

### Parameters
#### Path Parameters
- **catalog** (string) - Required - The name of the parent catalog for the schema.
- **schema** (string) - Required - The name of the schema of interest.

#### Query Parameters
- **include_browse** (boolean) - Optional - Defaults to `TRUE`. Whether to include catalogs for which the principal can only access selective metadata.

#### Request Body
This endpoint does not accept a request body.

### Request Example
```r
db_uc_schemas_get(
  catalog = "my_catalog",
  schema = "my_schema",
  include_browse = TRUE
)
```

### Response
#### Success Response (200)
- **schema_name** (string) - The name of the schema.
- **catalog_name** (string) - The name of the catalog the schema belongs to.
- **schema_owner** (string) - The owner of the schema.
- **schema_comment** (string) - A comment describing the schema.
- **created_at** (string) - Timestamp when the schema was created.
- ** Dbid ** (integer) - The unique identifier for the schema.

#### Response Example
```json
{
  "schema_name": "my_schema",
  "catalog_name": "my_catalog",
  "schema_owner": "user@example.com",
  "schema_comment": "This is my schema.",
  "created_at": "2023-10-27T10:00:00Z",
  " Dbid ": 12345
}
```
```

--------------------------------

### Connect to Databricks Workspace

Source: https://databrickslabs.github.io/brickster/reference/open_workspace

Establishes a connection to a Databricks workspace using provided host and token.

```APIDOC
## Connect to Databricks Workspace

### Description
Establishes a connection to a Databricks workspace using the provided host URL and authentication token. You can optionally assign a specific name to this connection.

### Method
N/A (This is an R function, not a direct HTTP API call)

### Endpoint
N/A

### Parameters
#### Arguments
- **host** (character) - The Databricks workspace URL. Defaults to the value returned by `db_host()`.
- **token** (character) - The Databricks workspace token. Defaults to the value returned by `db_token()`.
- **name** (character, optional) - The desired name to assign to the connection.

### Request Example
```R
# Example of calling the function (within an R environment)
# open_workspace(host = "https://your_databricks_host.cloud.databricks.com/", token = "your_personal_access_token", name = "MyDevWorkspace")
if (FALSE) { # \dontrun{
open_workspace(host = db_host(), token = db_token, name = "MyWorkspace")
} # }
```

### Response
#### Success Response
This function typically returns a connection object or `invisible(NULL)` upon successful connection.

#### Response Example
```R
# Upon successful connection, no explicit return value is printed, but the connection is established.
# You might check for active connections using other package functions if available.
```
```

--------------------------------

### POST /api/2.0/repos

Source: https://databrickslabs.github.io/brickster/reference/db_repo_create

Creates a new repository in the Databricks workspace and links it to a specified remote Git repository.

```APIDOC
## POST /api/2.0/repos

### Description
Creates a repo in the workspace and links it to the remote Git repo specified.

### Method
POST

### Endpoint
/api/2.0/repos

### Parameters
#### Query Parameters
- **host** (string) - Optional - Databricks workspace URL, defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token, defaults to calling `db_token()`.

#### Request Body
- **url** (string) - Required - URL of the Git repository to be linked.
- **provider** (string) - Required - Git provider. This field is case-insensitive. The available Git providers are `gitHub`, `bitbucketCloud`, `gitLab`, `azureDevOpsServices`, `gitHubEnterprise`, `bitbucketServer` and `gitLabEnterpriseEdition.`
- **path** (string) - Required - Desired path for the repo in the workspace. Must be in the format `/Repos/{folder}/{repo-name}`.
- **perform_request** (boolean) - Optional - If `TRUE` (default) the request is performed, if `FALSE` the httr2 request is returned _without_ being performed.

### Request Example
```json
{
  "url": "https://github.com/user/repo.git",
  "provider": "gitHub",
  "path": "/Repos/myfolder/myrepo",
  "perform_request": true
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created repository.
- **object_id** (integer) - The object ID of the created repository.
- **created_at** (string) - Timestamp of when the repository was created.
- **last_modified_at** (string) - Timestamp of when the repository was last modified.
- **url** (string) - The URL of the linked Git repository.
- **link** (string) - The URL to access the repository in the Databricks workspace.
- **status** (string) - The current status of the repository.
- **is_default** (boolean) - Whether this is the default repository.
- **exists_in_workspace** (boolean) - Whether the repository exists in the workspace.
- **tag** (string) - The tag associated with the repository.

#### Response Example
```json
{
  "id": 12345,
  "object_id": 67890,
  "created_at": "2023-10-27T10:00:00Z",
  "last_modified_at": "2023-10-27T10:00:00Z",
  "url": "https://github.com/user/repo.git",
  "link": "/repos/12345",
  "status": "SYNCED",
  "is_default": false,
  "exists_in_workspace": true,
  "tag": "main"
}
```
```

--------------------------------

### Get Information About a Command

Source: https://databrickslabs.github.io/brickster/reference/db_context_command_status

Retrieves information about a specific command executed within a Databricks execution context.

```APIDOC
## GET /api/2.0/commands/{command_id}/status

### Description
Get Information About a Command. This endpoint retrieves the status and details of a specific command that has been executed within a Databricks execution context on a given cluster.

### Method
GET

### Endpoint
`/api/2.0/commands/{command_id}/status`

### Parameters
#### Path Parameters
- **command_id** (string) - Required - The ID of the command to get information about.
- **cluster_id** (string) - Required - The ID of the cluster where the command was executed.
- **context_id** (string) - Required - The ID of the execution context.

#### Query Parameters
- **host** (string) - Optional - Databricks workspace URL, defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token, defaults to calling `db_token()`.
- **perform_request** (boolean) - Optional - If `TRUE` (default) the request is performed, if `FALSE` the httr2 request is returned _without_ being performed.

### Request Example
```json
{
  "cluster_id": "your_cluster_id",
  "context_id": "your_context_id",
  "command_id": "your_command_id"
}
```

### Response
#### Success Response (200)
- **status** (string) - The current status of the command (e.g., RUNNING, FINISHED, FAILED).
- **error_message** (string) - If the command failed, this field contains the error message.
- **result** (object) - The result of the command if it has finished successfully.

#### Response Example
```json
{
  "status": "FINISHED",
  "error_message": null,
  "result": {
    "data": [
      [1, "example"]
    ],
    "schema": [
      {"name": "col1", "type": "integer"},
      {"name": "col2", "type": "string"}
    ]
  }
}
```
```

--------------------------------

### Docker Image Connection

Source: https://databrickslabs.github.io/brickster/reference/docker_image

Establishes a connection to a Docker image using provided URL, username, and password. It's recommended to use environment variables for credentials.

```APIDOC
## Docker Image Connection

### Description
Provides connection information for Docker images, allowing you to specify the URL, username, and password for authentication.

### Usage
```R
docker_image(url, username, password)
```

### Arguments 
#### Path Parameters
- **url** (string) - Required - URL for the Docker image.
- **username** (string) - Required - User name for the Docker repository.
- **password** (string) - Required - Password for the Docker repository.

### Details
Uses basic authentication. It is **strongly** recommended that credentials are not stored in any scripts and environment variables should be used instead.

### See Also
- `db_cluster_create()`
- `db_cluster_edit()`
```

--------------------------------

### Cluster Management - Init Script Info

Source: https://databrickslabs.github.io/brickster/reference/init_script_info

Provides information about init scripts for Databricks clusters. It accepts storage information objects like s3_storage_info(), file_storage_info(), or dbfs_storage_info(). Note that file_storage_info() is specific to Databricks Container Services.

```APIDOC
## Init Script Info

### Description
This function is used to provide information about init scripts for Databricks clusters. It can accept various storage types for the init scripts.

### Method
N/A (This is a function within an R package, not a direct API endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **...**: Accepts multiple instances of `s3_storage_info()`, `file_storage_info()`, or `dbfs_storage_info()`.
  - `s3_storage_info()`: (Object) Information for S3 storage.
  - `file_storage_info()`: (Object) Information for file storage. Only available for clusters set up using Databricks Container Services.
  - `dbfs_storage_info()`: (Object) Information for DBFS storage.

### Request Example
```R
# Example usage (conceptual, actual R code would be needed)
init_script_info(s3_storage_info(bucket = "my-bucket", key = "path/to/script.sh"))
init_script_info(file_storage_info(path = "/databricks/init/script.sh"))
```

### Response
#### Success Response
N/A (This function configures cluster settings, no direct response data is returned in this format)

#### Response Example
N/A
```

--------------------------------

### Wait for Library Installations on Databricks Cluster

Source: https://databrickslabs.github.io/brickster/articles/cluster-management

Blocks execution until all libraries for a given Databricks cluster have finished installing. This is useful for ensuring dependencies are met before proceeding.

```r
wait_for_lib_installs(cluster_id = new_cluster$cluster_id)
```

--------------------------------

### List Available Databricks Runtime Versions (R)

Source: https://databrickslabs.github.io/brickster/reference/db_cluster_runtime_versions

Retrieves a list of available Databricks Runtime versions that can be used to launch a cluster. It takes the Databricks workspace URL and token as optional arguments. If perform_request is set to FALSE, it returns the httr2 request object without executing it.

```r
db_cluster_runtime_versions(
  host = db_host(),
  token = db_token(),
  perform_request = TRUE
)
```

--------------------------------

### DBFS Get Status

Source: https://databrickslabs.github.io/brickster/reference/db_dbfs_get_status

Retrieves file information for a given path in DBFS. It can return the actual request or the performed request depending on the `perform_request` argument.

```APIDOC
## DBFS Get Status

### Description
Get the file information of a file or directory in DBFS.

### Method
GET (This is implied by the function name and typical REST API patterns for retrieving status, although the specific HTTP method is not explicitly stated in the provided text.)

### Endpoint
(Endpoint path is not explicitly provided in the text, but would typically be something like `/api/2.0/dbfs/get_status`)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **path** (string) - Required - The absolute DBFS path of the file or directory (e.g., `/mnt/my-file.txt`).
- **host** (string) - Optional - Databricks workspace URL, defaults to calling `db_host()`.
- **token** (string) - Optional - Databricks workspace token, defaults to calling `db_token()`.
- **perform_request** (boolean) - Optional - If TRUE (default), the request is performed. If FALSE, the request object is returned without being performed.

### Request Example
(No explicit request body example is provided, as this is likely a GET request. The parameters would be sent as query parameters.)

### Response
#### Success Response (200)
- **path** (string) - The path of the file or directory.
- **is_dir** (boolean) - True if the path is a directory, false otherwise.
- **file_size** (integer) - The size of the file in bytes. If it's a directory, this might represent total size or be null.
- (Other relevant file metadata fields may be present)

#### Response Example
```json
{
  "path": "/mnt/my-file.txt",
  "is_dir": false,
  "file_size": 1024
}
```

### Error Handling
- If the file or directory does not exist, this call throws an exception with `RESOURCE_DOES_NOT_EXIST.`
```

--------------------------------

### Run a Command

Source: https://databrickslabs.github.io/brickster/reference/db_context_command_run

Executes a command (Python, SQL, Scala, or R) within a specified execution context on a Databricks cluster.

```APIDOC
## Run a Command

### Description
Executes a command within a specified execution context on a Databricks cluster. The command can be provided as a string or read from a file.

### Method
POST

### Endpoint
`/api/2.0/commands/execute` (Assumed, as no explicit endpoint is provided, but typical for command execution)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cluster_id** (string) - Required - The ID of the cluster to run the command on.
- **context_id** (string) - Required - The ID of the execution context.
- **language** (string) - Required - The language of the command. One of `python`, `sql`, `scala`, `r`.
- **command** (string) - Optional - The command string to execute.
- **command_file** (string) - Optional - The path to a file containing the command to execute.
- **options** (object) - Optional - A list of options to configure the command execution, e.g., `displayRowLimit`.
- **host** (string) - Optional - The Databricks workspace URL. Defaults to `db_host()`.
- **token** (string) - Optional - The Databricks workspace token. Defaults to `db_token()`.
- **perform_request** (boolean) - Optional - If `TRUE` (default), the request is performed. If `FALSE`, the `httr2` request object is returned.

### Request Example
```json
{
  "cluster_id": "your_cluster_id",
  "context_id": "your_context_id",
  "language": "python",
  "command": "print('Hello, Databricks!')"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the command execution.
- **status** (string) - The current status of the command execution (e.g., 'Running', 'Finished', 'Error').

#### Response Example
```json
{
  "id": "command_execution_id_123",
  "status": "Running"
}
```
```

--------------------------------

### Connect to Databricks Workspace (R)

Source: https://databrickslabs.github.io/brickster/reference/open_workspace

Opens a connection to a Databricks workspace using host and token credentials. It defaults to using environment variables or configuration for host and token if not provided. An optional name can be assigned to the connection.

```r
open_workspace(host = db_host(), token = db_token(), name = NULL)
```

```r
if (FALSE) { # \dontrun{
open_workspace(host = db_host(), token = db_token, name = "MyWorkspace")
} # }
```