Advanced Data Navigation

SlashDB allows for even more control in viewing databases using additional query string parameters.

sort

This feature enables sorting list of records.

Usage:

?sort=[column_name]
?sort=-[column_name]
?sort=[column_name_A],[column_name_B]

Value type: string

Default: depends on database collation

Applicable to: list of resources, list of arrays, vectors.

Examples:

/Customer?sort=Country - sort Customers by Country ascending

/Customer?sort=-Country - sort Customers by Country descending (minus before column name)

/Customer?sort=-Country,LastName - sort Customers by Country descending and LastName ascending

You may define by which columns and direction (ascending or descending) you want the data to be sorted.

distinct

This feature removes duplicate entries in vectors.

Usage:

?distinct

Value type: (no value)

Default: (not used)

Applicable to: list of arrays, vectors

Examples:

/Customer/Country.html?distinct - show only unique countries

limit and offset

Query string parameters limit and offset allow to define number of returned and skipped records. This feature allows to implement a pagination mechanism.

Usage:

?limit=[number_of_rows_to_acquire]
?offset=[number_of_rows_to_skip]
?limit=[number_of_rows_to_acquire]&offset=[number_of_rows_to_skip]

Value type: integer

Default: no limit and no offset

Applicable to: list of resources, list of arrays, vectors

Examples:

/Invoice.html?limit=10 - show only first 10 Invoices

/Invoice.html?offset=2 - skip first 2 Invoices and show all the rest

/Invoice.html?limit=10&offset=2 - show 10 Invoices but skip first 2

stream

This feature comes handy when requesting large amounts of data.
When query string parameter stream is set True, SlashDB utilizes streaming data transfer mechanizm of HTTP (Chunked Transfer Encoding). This allows to reduce amount of memory used while creating output and TTFB.
Header Transfer-Encoding: chunked is added to the response.
At this point streaming is supported only for "flat" (no depth or depth=0).
Also HTML format (GUI) does not support streaming.

Usage:

?stream=[true_or_false]

Value type: boolean (True or False)

Default: False

Applicable to: list of resources, list of arrays, vectors, single resource, single array, scalar

Examples:

/InvoiceLine.json?stream=True - stream all InvoiceLines (list of approx. 2240 objects)

depth

This feature is useful if you want to acquire objects together with all related data in single request. The value number indicates how many subsequent relations must be included (nested) in result.

Use with caution as high depth may return large amount of data or even all data in your database, resulting in slow response and possible timeouts.

Usage:

?depth=[depth_level]

Value type: integer

Default: 0 (a flat structure that contains object attributes)

Applicable to: list of resources, single resource

Examples:

/Customer/CustomerId/18.json - show only Customer object details (default depth)

/Customer/CustomerId/18.json?depth=1 - show Customer object with her Invoices and Employees

wantarray

This feature makes output always as a list.

SlashDB is a Resource Oriented Architecture. When making request to a canonical URL (contains only filtering on Primary Keys, which explicitly identifies a single resource) SlashDB does not pack returned object into form of a list. With query string wantarray=True you may force to put that object into a list anyway.

In case of canonical URLs, if the resource has not been found, we would get an 404, but in wantarray mode, we'll get an empty array [].

Usage:

?wantarray=[true_or_false]

Value type: boolean (True or False)

Default: False

Applicable to: single resource, single array, scalar

Examples:

/Customer/CustomerId/18.json - canocial URL, output not wrapped in a list

/Customer/CustomerId/18.json?wantarray=True - canocial URL, output wrapped in a list

/Customer/CustomerId/18/Country/USA.json - although URL contains filtering on Primary Key it's not canonical because it contains other filter (Country = USA)

/Customer/CustomerId/18/Country.json?wantarray=True - wantarray applied on a scalar

/Customer/CustomerId/18/Country,City.json?wantarray=True - wantarray applied on an array

wildcard

The query string parameter wildcard allows to change default wildcard character.

By default, SlashDB allows filtering by substring using * character e.g. /Customer/LastName/S* - customers with last name starting with letter "S".

In case you want to filter literally by asterisk character you must use tell SlashDB to use different character for wildcard e.g. wildcard=$.

Usage:

?wildcard=[string_representing_wildcard]

Value type: string

Default: * (asterisk character)

Applicable to: list of resources, list of arrays, vectors

Examples:

/Customer/Company/* Inc. - find all Customers whose company ends with "Inc."

/Customer/Company/$ Inc.?wildcard=$ - find all Customers whose company ends with "Inc." using different wildcard

separator

Allows to change default character , (comma) which is used when filtering for multiple values. Useful when one of the values contains a comma.

Usage:

?separator=[string_representing_separator]

Value type: string

Default: , (comma character)

Applicable to: list of resources, list of arrays, vectors

Examples:

/Invoice/InvoiceId/1,2,3 - get invoices 1, 2 and 3.

/Invoice/InvoiceId/1$2$3?separator=$ - same as above but using $ as a separator of values

/Invoice/BillingAddress/11, Place Bellecour.html?separator=$ - show Invoices that have BillingAddress "11, Place Bellecour" (contains a comma).

url string substitution

This feature allows to represent string using another string.

There are rare situations when value in filtering is part of URL syntax. For example "/" character normally would be interpreted as a path separator and couldn't be correctly used for filter value.

By default SlashDB will interpret "__" (double underscore character) as "/" (slash character).

Usage:

?[placeholder]=[meaning_of_the_placeholder]

Value type: string

Default: __=/ (double underscore character is interpreted as forward slash)

Applicable to: list of resources, list of arrays, vector, single resource, single array, scalar

Examples:

/Chinook/Artist/Name/AC__DC - double underscore is treated as forward slash
/Chinook/Artist/Name/AC_DC?_=/ - single underscore is treated as forward slash

TXT

nil visible for txt

This feature allows to force showing empty line for NULL values. Forcing empty lines might be useful when combining data with other requests to keep data in order. By default empty values are not shown to reduce document length.

Usage:

?nil_visible=[True_or_False]

Value type: boolean (True or False)

Default: False

Applicable to: vector

Examples:

/Customer/Company.txt - not showing empty values by default

/Customer/Company.txt?nil_visible=False - not showing empty values

/Customer/Company.txt?nil_visible=True - showing empty values as empty lines

XML

nil visible for xml

This feature allows to force showing empty line for NULL values. Forcing empty tags might be useful when combining data with other requests to keep data in order. By default empty values are not shown to reduce document length.

Usage:

?nil_visible=[True_or_False]

Value type: boolean (True or False)

Default: False

Applicable to: list of resources, list of arrays, vector, single resource, single array, scalar

Examples:

/Customer/CustomerId,Company.xml - not showing empty tags by default

/Customer/CustomerId,Company.xml?nil_visible=False - not showing empty tags

/Customer/CustomerId,Company.xml?nil_visible=True - showing tags with no value

XSD

cardinality

For XML schema (XSD) only, there is a special cardinality query parameter which sets the xsd:element maxOccurs attribute. By default it is set to cardinality=n.

Cardinality=1 is useful when we require a schema for individual resources, such as for canonical URLs with a primary key column only.

Usage:

?cardinality=[xsd_maxOccurs_value]

Value type:

• integer greater than 0
• string "n"
• string "unbounded"

Default: unbounded

Applicable to: list of resources, list of arrays, vectors

Examples:

/Invoice.xml?cardinality=1 - XSD contains maxOccurs="1"

CSV

headers

Determines if a CSV output (or input) should contain a with column names.

Usage:

?headers=[True_or_false]

Value type: boolean (True or False)

Default: True

Applicable to:

• PUT of csv document on list of resources, list of arrays, vectors
• POST of csv document on resource table endpoints

Examples:
/Chinook/Customer.csv - default (with headers)
/Chinook/Customer.csv?headers=True - with headers
/Chinook/Customer.csv?headers=False - without headers

csvNullStr

Allows to set NULL value in database when uploading CSV document (only POST or PUT).

The csv documents do not have specific character that would explicitly mean "no value". SlashDB provides a csvNullStr query parameter which defines the representation for a NULL value in parsed csv document.

This flag is useful only for nullable columns and does not affect the way the database driver handles NULL values.

Value type: string

Default: (empty string)

Applicable to:

• PUT of csv document on list of resources, list of arrays, vectors
• POST of csv document on resource table endpoints

Usage:

?csvNullStr=[string_representing_null_in_csv]

Examples:

Making a POST request to https://beta.slashdb.com/db/Chinook/Invoice.csv?csvNullStr=myNull with data:

InvoiceId,CustomerId,InvoiceDate,BillingAddress,BillingCity,BillingState,BillingCountry,BillingPostalCode,Total
1000,2,2666-01-01 00:00:00,myNull,Test City,Test State,Test Country,00 000,6.66

will result in passing to database NULL for BillingAddress.