Package {cloudosR}

Build Query String

Description

Internal function to build URL query string from list of parameters.

Usage

build_query_string(params)

Arguments

Value

Character. URL-encoded query string.

List Cohort Tables

Description

Retrieves the list of available database schemas and tables for a cohort.

Usage

cloudos.cohort_tables(profilename = "", cohort_id = "")

Arguments

Value

List with schema information including databases, tables, and columns.

Examples

## Not run: 
  # Get available schemas for a cohort
  schemas <- cloudos.cohort_tables(
    profilename = "production",
    cohort_id = "your-cohort-id"
  )
  
  # Display databases
  cat("Available databases:\n")
  for (db in schemas) {
    cat("  -", db$database, "\n")
  }

## End(Not run)

Configure Lifebit Platform Profile

Description

Stores API credentials and workspace context for a named profile. This is the required first step before any API wrapper call.

Usage

cloudos.configure(
  profilename = "",
  apikey = "",
  workspace_id = "",
  base_url = "https://cloudos.lifebit.ai",
  set_default = FALSE
)

Arguments

Value

Invisible NULL. Prints a success message.

Examples

## Not run: 
  cloudos.configure(
    profilename = "production",
    apikey = "your-api-key",
    workspace_id = "5c6d3e9bd954e800b23f8c62",
    set_default = TRUE
  )

## End(Not run)

List Lifebit Platform Profiles

Description

Lists configured profiles so users can confirm available environments.

Usage

cloudos.profile_list()

Value

Data frame with profile names and metadata (workspace_id, default, created_at, updated_at). Returns empty data frame if no profiles are configured.

Examples

## Not run: 
  profiles <- cloudos.profile_list()
  print(profiles)

## End(Not run)

Execute SQL Query (Orchestrator)

Description

High-level function that orchestrates the full query lifecycle: submit -> poll status -> fetch results as dataframe.

Usage

cloudos.query(
  profilename = "",
  cohort_id = "",
  sql = "",
  poll_interval = 2,
  max_wait = 600,
  page_size = 1000,
  all_pages = TRUE
)

Arguments

Details

IMPORTANT: Pagination works by submitting separate tasks for each page. When all_pages=TRUE, this function submits multiple async tasks (one per page), waits for all to complete, and combines the results. This may take longer for large result sets.

Value

Data frame with query results.

Examples

## Not run: 
  # Fetch all results
  results <- cloudos.query(
    profilename = "production",
    cohort_id = "699edb4380a6867895f0c9e1",
    sql = "SELECT person_id, gender_concept_id FROM person LIMIT 500"
  )
  
  # Fetch only first page
  results_page1 <- cloudos.query(
    profilename = "production",
    cohort_id = "699edb4380a6867895f0c9e1",
    sql = "SELECT person_id FROM person",
    all_pages = FALSE,
    page_size = 100
  )

## End(Not run)

Fetch Async Query Results

Description

Fetches results from a completed async SQL task and returns as a dataframe.

Usage

cloudos.query_results(profilename = "", task_id = "")

Arguments

Details

Note: Pagination is controlled when submitting the query via cloudos.query_submit_async(), not when fetching results. This function returns whatever page the task was configured for.

Value

Data frame with query results from the page configured at submission time.

Examples

## Not run: 
  # Fetch results for a task (returns the page configured when query was submitted)
  results <- cloudos.query_results(
    profilename = "production",
    task_id = "69a5c58d626fe626da0025ce"
  )

## End(Not run)

Check Async Query Status

Description

Returns the current status and metadata for a submitted async SQL task.

Usage

cloudos.query_status(profilename = "", task_id = "")

Arguments

Value

List with task status, count of results, and other metadata.

Examples

## Not run: 
  status <- cloudos.query_status(
    profilename = "production",
    task_id = "69a5c58d626fe626da0025ce"
  )
  print(status$status)
  print(status$count_of_results)

## End(Not run)

Submit Async SQL Query

Description

Starts async SQL execution for a cohort and returns a task ID for tracking.

Usage

cloudos.query_submit_async(
  profilename = "",
  cohort_id = "",
  sql = "",
  pagination = NULL
)

Arguments

Value

List with task metadata including task_id, status, and full response.

Examples

## Not run: 
  # Submit query without pagination
  task <- cloudos.query_submit_async(
    profilename = "production",
    cohort_id = "699edb4380a6867895f0c9e1",
    sql = "SELECT person_id FROM person LIMIT 100"
  )
  
  # Submit query with pagination for page 2 with 50 rows per page
  task <- cloudos.query_submit_async(
    profilename = "production",
    cohort_id = "699edb4380a6867895f0c9e1",
    sql = "SELECT person_id FROM person",
    pagination = list(pageNumber = 2, pageSize = 50)
  )
  print(task$task_id)

## End(Not run)

Validate SQL Query

Description

Validates SQL syntax and references before execution.

Usage

cloudos.sql_validate(profilename = "", sql = "")

Arguments

Value

List with validation results including isValid, tableReferences, and columnReferences.

Examples

## Not run: 
  # Validate a SQL query
  validation <- cloudos.sql_validate(
    profilename = "production",
    sql = "SELECT person_id FROM person WHERE year_of_birth >= 1960"
  )
  
  if (validation$isValid) {
    cat("SQL is valid\n")
    cat("Tables:", paste(validation$tableReferences, collapse = ", "), "\n")
  } else {
    cat("SQL is invalid:", validation$message, "\n")
  }

## End(Not run)

Convert Query Results to Dataframe

Description

Internal function to convert API response data to a dataframe.

Usage

convert_results_to_dataframe(data, column_names)

Arguments

Value

Data frame with query results.

Format Error Message with Generic Access Denial

Description

Returns a generic error message that doesn't leak information about resource existence. Used for schema/table access errors in accordance with security policy.

Usage

format_generic_access_error(resource_type, resource_name = NULL)

Arguments

Value

Character. Generic error message.

Get Config Directory Path

Description

Internal function to get the Lifebit Platform config directory path. Uses tools::R_user_dir() for CRAN-compliant persistent storage. Can be overridden with CLOUDOS_CONFIG_DIR environment variable.

Usage

get_config_dir()

Value

Character. Path to config directory.

Get Config File Path

Description

Internal function to get the Lifebit Platform config file path. Config file is stored in the user's R config directory as .cloudos_config.json using tools::R_user_dir() for CRAN compliance.

Usage

get_config_file()

Value

Character. Path to config file.

Handle API Error Response

Description

Internal function to handle API error responses and generate user-friendly error messages.

Usage

handle_api_error(response, endpoint)

Arguments

Value

NULL (throws error with formatted message).

Make HTTP GET Request

Description

Internal function to make authenticated GET requests to Lifebit Platform API.

Usage

http_get(profile, endpoint, query_params = list())

Arguments

Value

Parsed JSON response.

Make HTTP POST Request

Description

Internal function to make authenticated POST requests to Lifebit Platform API.

Usage

http_post(profile, endpoint, body = list(), query_params = list())

Arguments

Value

Parsed JSON response.

Make HTTP Request with Retry

Description

Internal function to make HTTP requests with retry logic for transient failures.

Usage

http_request_with_retry(
  method,
  profile,
  endpoint,
  body = list(),
  query_params = list(),
  max_retries = 3,
  retry_delay = 2
)

Arguments

Value

Parsed JSON response.

Check if Response Indicates Access Denial

Description

Internal function to check if API response indicates access denial (could be either non-existent or unauthorized).

Usage

is_access_denied(response)

Arguments

Value

Logical. TRUE if access is denied.

Load Profile Configuration

Description

Internal function to load a specific profile's configuration. If profilename is empty or NULL, loads the default profile.

Usage

load_profile(profilename = "")

Arguments

Value

List with profile configuration (apikey, workspace_id, base_url).

Null-coalescing Operator

Description

Returns the left-hand side if it's not NULL, otherwise returns the right-hand side.

Usage

x %||% y

Arguments

Value

x if not NULL, otherwise y.

Paginate Results

Description

Internal function to handle pagination of large result sets.

Usage

paginate_results(data, page = 0, page_size = 20)

Arguments

Value

List with paginated data and metadata.

Parse JSON Response

Description

Internal function to safely parse JSON response from API.

Usage

parse_json_response(response)

Arguments

Value

Parsed JSON object.

Print method for cloudos_tables

Description

Print method for cloudos_tables

Usage

## S3 method for class 'cloudos_tables'
print(x, ...)

Arguments

Value

The cloudos_tables object x, returned invisibly. Called primarily for its side effect of printing a formatted list of schemas and tables to the console.

Validate Required String Parameter

Description

Internal function to validate that a string parameter is not empty or NULL.

Usage

validate_required_string(value, param_name)

Arguments

Value

NULL (throws error if validation fails).