🎯API Stability
Short-TermThis API may change in future versions. Use with caution in production environments.

Summary

The createOrUpdateExternalFunction() mutation registers or updates an external function in LogScale. External functions extend the LogScale query language by calling an external HTTP endpoint during query execution. LogScale passes the specified parameters to the endpoint and incorporates the response into the query result.

The mutation is idempotent: if a function with the given name already exists, LogScale updates its definition in place; otherwise, it creates a new function. After registering a function, add it to the allowlist for at least one language version using addFunctionsToAllowList() before the function becomes available in queries. A function that has not been allowlisted cannot be called, even if its specification is valid.

Syntax

graphql
createOrUpdateExternalFunction(
      input: CreateOrUpdateExternalFunctionInput!
   ): ExternalFunctionSpecificationOutput!

The mutation accepts a single required input argument of type CreateOrUpdateExternalFunctionInput!. The name field identifies the function; if a function with that name already exists, LogScale updates it rather than creating a duplicate. The procedureURL field specifies the HTTP endpoint that LogScale calls when a query invokes this function. The kind field controls the execution model — for example, General for standard HTTP invocation. The parameters field defines the typed argument specification that callers must satisfy; each entry provides a parameter name and its type, such as String. The description field supplies human-readable documentation displayed in tooling and the function catalog. All fields are required.

The mutation returns an ExternalFunctionSpecificationOutput! object representing the persisted state of the function. See the Returned Values section for available fields.

Example

Raw
graphql
mutation {
  createOrUpdateExternalFunction(input:
       { name: "my-ext-function",
         procedureURL: "https://function.company.com",
         parameters: [{name: "parameter1", parameterType: String } ],
         description: "Cool External Function",
         kind: { name: General }
      } )
  { name }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  createOrUpdateExternalFunction(input: ^
       { name: \"my-ext-function\", ^
         procedureURL: \"https://function.company.com\", ^
         parameters: [{name: \"parameter1\", parameterType: String } ], ^
         description: \"Cool External Function\", ^
         kind: { name: General } ^
      } ) ^
  { name } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  createOrUpdateExternalFunction(input:
       { name: \"my-ext-function\",
         procedureURL: \"https://function.company.com\",
         parameters: [{name: \"parameter1\", parameterType: String } ],
         description: \"Cool External Function\",
         kind: { name: General }
      } )
  { name }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();

Input Parameters

The input argument accepts a CreateOrUpdateExternalFunctionInput object. All five fields are required. The name field is the unique identifier for the function used when calling it in queries and when referencing it in allowlist operations; it must match exactly, including case. The procedureURL field is the HTTP endpoint that LogScale calls during query execution. The kind field specifies the execution model via a KindInput object; use General for standard HTTP invocation. The parameters field is a list of ParameterSpecificationInput entries that define each argument the function accepts, including its name and type. The description field provides documentation displayed in tooling. The following table describes each field:

Table: CreateOrUpdateExternalFunctionInput Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
descriptionStringyes Preview The description for the external function.
kindKindInputyes Preview The kind of external function. It defines how the external function is executed. See KindInput.
nameStringyes Preview The name of the external function.
parametersParameterSpecificationInputyes Preview The parameter specifications for the external function. See ParameterSpecificationInput.
procedureURLStringyes Preview The URL for the external function.

Returned Values

The mutation returns an ExternalFunctionSpecificationOutput object that reflects the persisted state of the function after the create or update operation. The returned fields mirror the input: name is the function identifier, procedureURL is the registered endpoint, kind describes the execution model as a KindOutput object, parameters is the list of argument specifications as ParameterSpecificationOutput entries, and description is the stored documentation string. Verify these values to confirm that LogScale persisted the intended configuration. The following table describes the available fields:

Table: ExternalFunctionSpecificationOutput Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
descriptionStringyes Short-Term The description for the external function.
kindKindOutputyes Short-Term The kind of external function, how it's executed. See KindOutput.
nameStringyes Short-Term The name of the external function.
parametersParameterSpecificationOutputyes Short-Term The parameter specifications for the external function. See ParameterSpecificationOutput.
procedureURLStringyes Short-Term The URL for the external function.