CS.SPARK_XCALL UDF function reference

Spark services can be set up to call other Spark services. Any Spark service can become a function that can be called from any other Spark service. This feature is known as Xcall and is defined as a function within an Excel workbook.

Please review Tutorial: Define CS.SPARK_XCALL UDF first if you are not familiar with Xcall.

Considerations

Although CS.SPARK_XCALL is very powerful, use it carefully.
- Xcall has additional network and resource overhead that will increase overall response latency.
- Instead of using multiple CS.SPARK_XCALL to fetch single items from the same downstream, use an [output_template] to retrieve all the outputs at the same time.
- If your upstream service requires making multiple downstream calls at one time, use Array Xcall for scaling.
CS.SPARK_XCALL is a dynamic array function that spills results outside of a single cell.
Although the [output_template] is optional, it is strongly recommended to define the [output_template] if you have multiple outputs or table outputs.
- This ensures that the outputs are always returned in the same position to be referenced by the formulas in the upstream service.
- Tables in the output template shoan arrayuld have the full dimension of the table provisioned. It may appear unusual to have large blank areas, but this ensures that the outputs can be referenced correctly by the formulas in the upstream service.
If any CS.SPARK_XCALL inputs are tables of single columns, then you must add !treat_as_table and <input name> as additional parameters at the end of the function.
- Example: CS.SPARK_XCALL("myfolder/myservice", , , "table1column", B2:B11, "!treat_as_table" , "table1column") where the downstream input name is table1column and the values are in B2:B11.
You can wrap CS.SPARK_XCALL with an IF function to only make the call when needed. This helps to improve performance.
- If the IF function will not run CS.SPARK_XCALL at the time of upload, make the default output return an array that is the same size as the [output_template]. Upon upload, Spark uses this area to bound the size of the returned outputs. If this is set to too small of an area, the responses may be truncated.
- You can use the SEQUENCE function to populate a blank array. For example, if the [output_template] has the dimension of 6 rows × 4 columns, then the conditional function could be defined as =IF(A1=FALSE, SEQUENCE(6, 4, 0, 0), CS.SPARK_XCALL(...)).
Recursive Xcall where the same downstream service is looped back will not work. For example, in the sequence A → B → C → B, the last B will not be invoked.

Service discovery

These forms of the CS.SPARK_XCALL function can be used for discovery of Spark services. These definitions do not work when compiled in Neuron.

=CS.SPARK_XCALL()

Discover folders you have access to.

=CS.SPARK_XCALL({folder})

Discover services you have inside the folder.
Example: =CS.SPARK_XCALL("myfolder")

=CS.SPARK_XCALL({folder}/{service}[])

Discover service versions for the service.
Example: =CS.SPARK_XCALL("myfolder")

=CS.SPARK_XCALL("{folder}/{service}[version]")

View the input template for [input_location] of the downstream service. If [version] is not defined, the latest service version will be referenced. Using [input_name_or_values] is preferred to using input templates.
Example 1: myfolder/myservice
Example 2: myfolder/myservice[1] takes the latest major version 1.
Example 3: myfolder/myservice[1.2] takes the latest minor version 1.2 .
Example 4: myfolder/myservice[1.2.3]

Function parameters

CS.SPARK_XCALL(service, [input_location], [output_template], [input_name_or_values], [input_name_or_values])

How parameters are used may depend on the type of CS_SPARK_XCALL definition. See Tutorial: Define CS.SPARK_XCALL UDF for examples of each definition.

Downstream inputs to send

Downstream outputs to receive

Recommended CS.SPARK_XCALL definition

Any number of inputs and types

1 single value output

Xcall without output template

Any number of inputs and types

2+ single value output OR 1+ table outputs

Xcall with output template

Make multiple Xcall at a time with single value inputs only

1+ single value outputs

Array Xcall for scaling

`[service]`

Service URI expressed in {folder}/{service}[version] format.

Example 1: myfolder/myservice
Example 2: myfolder/myservice[1] takes the latest major version 1.
Example 3: myfolder/myservice[1.2] takes the latest minor version 1.3 .
Example 4: myfolder/myservice[1.3.2]

`[input_location]`

Reference to a range where the input template is defined. In Tutorial: Define CS.SPARK_XCALL UDF [input_location] is always left empty because the name-value pairs method of [input_name_or_values] is easier to use.

The input template of a Spark service can be found using =CS.SPARK_XCALL("{folder}/{service}[version]").
Input template is defined by a range reference. Inside this range:
- The left most column is for the input names.
- The columns to the right define the area that contain values or references to the input values.
  - Single values need only one cell.
  - Tables should include the table headings.
This can be used in conjunction with the [input_name_or_values] name-value pairs. If an input is in both [input_location] and [input_name_or_values], the input value in [input_name_or_values] takes precedence.

`[output_template]`

This defines how outputs are written back to the dynamic spill range, including which outputs and the order in which they are returned.

CS.SPARK_XCALL definition

Description

Example

Xcall without output template

Spark will use its own logic to lay out how outputs returned from the downstream service are written to the upstream service.

This is not recommended.

Xcall with a single value output template

Name or reference to the name of an output from the downstream service.

Example 1: B10 Example 2: scalar_det

Xcall with range output template

Output template is defined by a range reference. Inside this range:

The left most column is for the output names.
The columns to the right define the space where the outputs will be placed. Single values need only one cell. Tables should have the table headings and the maximum size of the output response allocated.

Example: C15:E15

Array Xcall for scaling

Output template is defined by a range reference. This should be arranged as a 1 row × n column range of output names.

Example: B9:D12

`[input_name_or_values], [input_name_or_values]`

The name-value pairs method is used to include inputs or request_meta to the downstream service. The parameters should always be provided in pairs:

Name or reference to the name of the input(s).
Value or reference to the values of the input(s).

CS.SPARK_XCALL definition

Description

Example

Xcall without output template OR Xcall with output template

Name or reference to the name of the n^th input to the downstream. , Value or reference to the values of the n^th input to the downstream.

Example 1: "scalar",C3 Example 2: B3,C3Example 3: "matrix",C5:D7 Example 4: B5,C5:D7

Array Xcall for scaling

Name or reference to the name of the n^th input to the downstream. , Value or reference to the values of the n^th input from the downstream.

Example 1: C3,C4:C6 single column Example 2: C3,C4:C6,D3,D4:D6 separate columns Example 3: C3:D3,C4:D6 contiguous columns

Request meta

Certain request_meta can be used with Xcall using additional [input_name_or_values], [input_name_or_values].

`#service_category`

Use with [input_name_or_values] to define the Sub functions with subservices to run.

Example 1: "#service_category", "Subservice1"
Example 2: "#service_category", "Subservice1,Subservice2"
Example 3: "#service_category", C4:C6 where C4:C6 is a list of subservices.

Trace `Xcall` iterations

The downstream Xcall calls can be traced using the request_meta debug_xcall.

Open the API Tester for the service.
In API request (inputs), select Raw view.
In the request_meta, add a comma , at the end of the last entry and then add "debug_xcall": true.
Submit the API call.
In In API response (outputs), select Raw view. Under response_data, outputs, additional_outputs contains an xcall_log array with a list of downstream Xcalls made and the associated call_id.

Sample xcall_log

{
    "response_data": {
        "outputs": {
            ...,
            "additional_outputs": {
                "xcall_log": {
                    "trace_id": "d22ac2e5-0c81-4ffd-8310-8d0332b6666b",
                    "total_xcall_count": 1,
                    "total_xcall_process_time": 4,
                    "xcalls": [
                        {
                            "service": "xcalls/ab_operations",
                            "xcall_id": [
                                "01a06273-78c7-74df-8485-da2f7db0feed"
                            ],
                            "xcall_self": false,
                            "xcall_count": 1,
                            "xcall_process_time": 4,
                            "xcall_process_time_breakdown": [
                                4
                            ],
                            "xcalls": []
                        }
                    ]
                }
            }
        },
        "warnings": null,
        "errors": null
    },
    "response_meta": {
        ...
    }
}

Last updated 11 hours ago

Considerations

Service discovery

Function parameters

[service]

[input_location]

[output_template]

[input_name_or_values], [input_name_or_values]

Request meta

#service_category

Trace Xcall iterations

`[service]`

`[input_location]`

`[output_template]`

`[input_name_or_values], [input_name_or_values]`

`#service_category`

Trace `Xcall` iterations