How to Set Query Parameters

Learn the fundamentals of working with query parameters in your HTTP Connector Functions in accordance with API documentation.

Query parameters allow you to refine and tailor the results of a Connector Function. Use parameters to sort, filter, set limits, offset an index, and more. This article uses the Tulip Table API parameters, but other APIs may have differing parameter requirements. Make sure you check the documentation to ensure that you’re using correct syntax and specifications.

Querying with Filters

Filters can be very useful to extract only the data you are interested in. These filters can sometimes be a bit tricky with their syntax. The following outlines how each is formed in the example of a GET request for records, followed by a full example.

Field names for custom fields are always prefixed with a five-digit string identifier. These can be found most easily after a GET all request to check the true name of the field.

• Ex. "field"="maytq_scrap_count"

Argument values are often straight forward. If it is a text value, make sure to put it in quotes.

• Ex. "arg":15

Match the function type you'd like to use.

• Ex. "functionType":"greaterThan"

A full request for this might look something like this:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field":"maytq\_scrap\_count","arg":15,"functionType":"greaterThan"}]&filterAggregator=any

How to Find Query Parameters in Documentation

To locate the available query parameters for your request, navigate to the API documentation. If you’re using the Tulip Table API, you can find the documentation at: your-instance.tulip.co/apiDocs.
Select the request you want to use then scroll down to the Parameters tab.

Each individual method has its own set parameters, however, not every request has associated parameters. Make sure to note what’s available in the documentation beforehand.

Query Parameters Syntax

Queries for parameter syntax relies on a query string format. This format assigns values to specified parameters, with the query string itself part of the URL.

In the Connector Function Editor, click Add Parameter to create a new query parameter.

There are two parts to a query parameter: a key and a value. The key is the name of the parameter and the value is the information that sets the parameter for the results.

Query parameters syntax uses Dot Notation, which specifies the exact type of parameter. Ensure the writing case matches the API standard of the other system.

Apply Common Parameters to Connector Functions

In order to set a parameter to your connector function, first identify the parameter you want to use in the API documentation. Parameters have varying requirements for each, so let’s go over what they look like.

Limits

Limits set a designated cap for the returned results. Note that some limits have default settings, so be sure to check the API documentation to understand the initial value.

Example
We want to get no more than 70 records when the connector function runs. Luckily, the default value for the limit in this request is 10 and the highest is 100. The syntax for the query parameter should look like the following:

Filters

Filters separate and refine the results based on the given information of the parameter.

Filters have three parts to them, which you must write in individual parameters:

• Field - the name of the column in the table
• Function Type - the comparison function type
• Argument - the value to compare the results to

Each filter has 3 parts and each complete filter is an Object. Using Dot Notation to write each key, specify the type of parameter (‘filter’), the filter number (0 through n), and the part of the filter (‘field’, ‘functionType’, or ‘arg’). There must be a parameter for all three parts of the filter.

Example
We want to make sure that the results of the connector function show only values of a specific field (eubmc_value) that equals the specified input value (consumable) of the function. Because this is our first filter in the parameters of the function, the filter number is 0. This means that every key for this filter will start with ‘filter.0’. The syntax for this filter should look like the following:

Sorting

Sorting results prioritizes the view based on the information of the parameter. The sorted results determine which are included in aggregations. You can have multiple sorting functions, however the order of options determines the sort priority.

Sorting functions have two parts to them:

• sortBy - the field you want to sort the results by
• sortDir - the direction of the sort, either ascending (asc) or descending (desc)

Each sort function has 3 parts. Using Dot Notation to write each key, specify the type of parameter (‘sortOptions’), the sorting number (0 through n), and the sorting argument (‘sortBy’ or ‘sortDir’). There must be a parameter for all three parts of the sort function in order for it to work.

Example
We want the results of the connector function to sort by the most recent updated field in an ascending order. Because this is our first sort function, the sorting number is 0. This means that both keys for this sort will start with ‘sortOptions.0’. For the sortBy key, the value is a special value (‘_updatedAt’) derived from the API documentation to sort through updated fields. The syntax for these parameters should look like the following:

Offsets

Offsets determine the index for the returned result to start at. This parameter is used for pagination, not the order of records which is determined by sorting parameters. The value of the parameter must be an integer that is greater than or equal to 0.

Example
We want to only view the records from after the 5th position, so that we don’t see the top 5 results. The syntax for the query parameter should look like the following:

Filter Aggregators

Filter aggregators determine how the filters in the parameters are combined. The two values to choose from are ‘any’ and ‘all’. The value ‘all’ means that all the filters must have a record in order for the record to be included in the results. The ‘any’ value means that at least one of the filters must match a record in order for it to be included in the results. The default value is ‘all’, regardless of whether or not you set the parameter.

Example
We have a series of filters in the query parameters, but we only need one of those filters to be true in order for the records to match our request. The syntax for the query parameter should look like the following:

Multiple Filters

In some cases, you may have multiple filters to check in the table. In this case, you can add multiple to the filters object. This might look something like this:

filters=[{"field":"maytq\_scrap\_count","arg":15,"functionType":"greaterThan"},{"field":"maytq\_scrap\_reason","arg":"scratch","functionType":"equal"}]

Further Reading

• An Overview of HTTP Connectors
• How to Create and Configure an HTTP Connector Function
• How to Use the Table API