http_request function

Applies to: check marked yes Databricks SQL check marked yes Databricks Runtime 16.2 and above

Makes an HTTP request using a defined HTTP connection.

This function requires named parameter invocation.

Syntax

http_request( { CONN => connectionName |
                METHOD => httpMethod |
                PATH => path |
                HEADERS => headerMap |
                PARAMS => paramMap |
                JSON => jsonStr  } [, ..] )

Arguments

An error is raised if a parameter is specified more than once.

  • connectionName

    A STRING constant referencing an existing HTTP connection identifier. This argument is required

  • httpMethod

    A STRING constant expression representing the HTTP method to use. The following methods are supported: 'GET', 'POST', 'PUT', 'DELETE', 'PATCH'. This argument is required.

  • path

    A STRING constant expression which gets appended to the base_path of the connection URL. The path must not contain directory traversal (../..). This argument is required.

  • headerMap

    An optional MAP<STRING, STRING> containing request headers. The default is NULL.

  • paramMap

    An optional MAP<STRING, STRING> with request query params in JSON format. The default is NULL.

  • jsonStr

    An optional JSON string expression with the request body.

Returns

A STRUCT<status_code INT, text STRING> where

  • status_code is the HTTP status code of the response from the external service. For example: 200 or 403.
  • text is the response returned by the external service. Typically, this is a JSON string.

Examples

-- Set up a connect to Slack.
> CREATE CONNECTION slack_conn
  TYPE HTTP
  OPTIONS (
    host 'https://slack.com',
    port '443',
    base_path '/api/',
    bearer_token 'xoxb-xxxxx'
  );

-- Request to the external service
> SELECT http_request(
    conn => 'slack_conn',
    method => 'POST',
    path => '/chat.postMessage',
    json => to_json(named_struct(
      'channel', channel,
      'text', text
    ))
    headers => map(
       'Accept', "application/vnd.github+json",
    )
  );

Limitations

  • The http_request function is rate limited. It is designed for interactive and agent-based use cases, not for high-volume batch queries. If you run http_request across many rows in a single query, requests might be throttled and result in errors. To work around this, use the Databricks SDK for Python to send requests in smaller batches with delays between them. For new code, Databricks recommends using the Unity Catalog connections proxy endpoint with the provider's SDK instead of http_request.
  • Last updated on