Back to top
  Back to overview

HTTP functions

These functions can be used when opening and submitting remote web requests, and webhooks.

Function Description
http::head() Perform a remote HTTP HEAD request
http::get() Perform a remote HTTP GET request
http::put() Perform a remote HTTP PUT request
http::post() Perform a remote HTTP POST request
http::patch() Perform a remote HTTP PATCH request
http::delete() Perform a remote HTTP DELETE request

http::head

The http::head function performs a remote HTTP HEAD request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error.

http::head(string) -> null

If an object is given as the second argument, then this can be used to set the request headers.

http::head(string, object) -> null

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::head('https://surrealdb.com');
null

To specify custom headers with the HTTP request, pass an object as the second argument:

SELECT * FROM http::head('https://surrealdb.com', {
	'x-my-header': 'some unique string'
});
null

http::get

The http::get function performs a remote HTTP GET request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::get(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

http::get(string, object) -> value

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::get('https://surrealdb.com');
-- The HTML code is returned

To specify custom headers with the HTTP request, pass an object as the second argument:

SELECT * FROM http::get('https://surrealdb.com', {
	'x-my-header': 'some unique string'
});
-- The HTML code is returned

http::put

The http::put function performs a remote HTTP PUT request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::put(string, object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::put(string, object, object) -> value

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::put('https://dummyjson.com/comments', {
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
});
{
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
}

http::post

The http::post function performs a remote HTTP POST request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::post(string, object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::post(string, object, object) -> value

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::post('https://dummyjson.com/comments/1', {
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
});
{
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
}

http::patch

The http::patch function performs a remote HTTP PATCH request. The first parameter is the URL of the remote endpoint, and the second parameter is the value to use as the request body, which will be converted to JSON. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::patch(string, object) -> value

If an object is given as the third argument, then this can be used to set the request headers.

http::patch(string, object, object) -> value

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::patch('https://dummyjson.com/comments/1', {
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
});
{
  "id": 1,
  "body": "This is some awesome thinking!",
  "postId": 100,
  "user": {
    "id": 63,
    "username": "eburras1q"
  }
}

http::delete

The http::delete function performs a remote HTTP DELETE request. The first parameter is the URL of the remote endpoint. If the response does not return a 2XX status code, then the function will fail and return the error. If the remote endpoint returns an application/json content-type, then the response is parsed and returned as a value, otherwise the response is treated as text.

http::delete(string) -> value

If an object is given as the second argument, then this can be used to set the request headers.

http::delete(string, object) -> value

The following example shows this function, and its output, when used in a select statement:

SELECT * FROM http::delete('https://dummyjson.com/comments/1');
null

To specify custom headers with the HTTP request, pass an object as the second argument:

SELECT * FROM http::delete('https://dummyjson.com/comments/1', {
	'x-my-header': 'some unique string'
});
null