Product Documentation

FairCom REST API Reference

Previous Topic

Next Topic

Find

Search or query records via a specific index. There are 3 ways to search for records. The normal find, and two grouped under advanced_find:

  • find
  • advanced_find
    • find_set
    • find_record

See also Rest Default Date and Time Format.

Previous Topic

Next Topic

Find

Type: POST

URL: /ctree/api/v1/query/{db}/{table}/{index}

Parameters:

  • db (required) string (path) - Database Name
  • table (required) string (path) - Table Name
  • index (required) string (path) - Index Name
  • top (required) integer (query) - Determine the maximum number of records to be returned.
  • skip integer (query) - Skip over the specified number of records before returning records.

Body:

For the first field in the specified index you can supply a field value and a comparison operator to find records starting at a single place in an index, or you can supply two field values to find records in the index between two places in the index.

The field name is used as the key to an object containing the operator, value, and optional upper and lower values. The object consists of:

operator is a required string indicating how to compare records to the value. Valid operators are "<", "<=", ">=", ">" and "between".

value is a required string, boolean, or number to compare the records with.

lowervalue is an optional string, boolean, or number used with the "between" operator to be the lower part of the range. Records that match the lowervalue will be included in the result. Mutually exclusive with excludelowervalue.

excludelowervalue is the same as lowervalue except records that match the excludelowervalue will NOT be included in the result. Mutually exclusive with lowervalue.

uppervalue is an optional string, boolean, or number used with the "between" operator to be the upper part of the range. Records that match the uppervalue will be included in the result. Mutually exclusive with excludeuppervalue.

excludeuppervalue is the same as uppervalue except records that match the excludelowervalue will NOT be included in the result. Mutually exclusive with uppervalue.

After the field name/compare details object the following settings can be added:

filter is an optional string (default is no filter) using the c-tree filtering syntax that can be used to add additional criteria not in the selected index. For instance, custcity = "Columbia" would exclude records from the find set that don't have "Columbia" in the custcity field.

reverse is an optional Boolean (default is false) that when set to true will cause the result set to be returned in the opposite order.

select is an optional array of strings (default is all fields) indicating which fields in the record to include in the result set. If you only needed 3 fields from a large record for instance, you could put the 3 field names into this array and the result set would only include those fields. Unneeded data is left out.

Example: Using the "name" index, find 25 or fewer records whose part_name field sort alphabetically after "A":

POST

https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=25

{
"find":{
"part_name"{
"operator": ">",
"value": "A"
}
}
}

Example: Using the name index, find 25 or fewer records whose part_name field starts with "B".

POST

https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=25

{
"find":{
"part_name":{
"operator": "between",
"lowervalue": "B",
"excludeuppervalue": "C"
}
}
}

Example: Using the name index, find 25 or fewer records whose part_name field sorts after "A" and has a part_year of 2013. Note part_year does not need to be part of the provided index.

POST https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=25
{
"find":{
"part_name":{
"operator": ">",
"value": "A"
}
},
"filter":"part_year=2013"
}

Example: Using the name index, find 25 or fewer records whose part_name field sorts after "A". Only return the part_number and _part_description fields:

POST https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=25{
"find":{
"part_name":{
"operator": ">",
"value": "A"
}
},
"select":[
"part_number",
"part_description"
]
}

Previous Topic

Next Topic

Advanced find_set

Advanced find_set allows you to find based on a number of bytes in the selected index.

Type: POST

URL: /ctree/api/v1/query/{db}/{table}/{index}

Parameters:

  • db (required) string (path) - Database Name
  • table (required) string (path) - Table Name
  • index (required) string (path) - Index Name
  • top (required) integer (query) - Determine the maximum number of records to be returned.
  • skip integer (query) - Skip over the specified number of records before returning records.

Body:

length is a required number indicating a maximum number of bytes in the index that must match the supplied value to be included.

fields is a required list of field names and values. Included fields must be in the selected index. Records whose index segments start with the supplied values will be returned.

Example: Find the first 3 records where part_name starts with "Wide"

POST https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=3

Body:

{
"advanced_find":{
"find_set": {
"length": 4,
"fields":{
"part_name": "Wide"
}
}}
}
{

Previous Topic

Next Topic

Advanced find_record

Advanced find_record allows you to perform a find utilizing all index segments in the selected index.

Type: POST

URL: /ctree/api/v1/query/{db}/{table}/{index}

Parameters:

  • db (required) string (path) - Database Name
  • table (required) string (path) - Table Name
  • index (required) string (path) - Index Name
  • top (required) integer (query) - Determine the maximum number of records to be returned.
  • skip integer (query) - Skip over the specified number of records before returning records.

Body:

operator is a required string indicating how to compare records to the value. Valid operators are "<", "<=", ">=", ">". This string is under find_record.

fields is a required object containing a list of field names and values. There should be a field and value for each segment of the index. This object is under advanced_find.

Example: Using the name index (part_name then part_number) find the record where part_name is "Part1" and part_number is 1:

POST https://localhost:8443/ctree/api/v1/query/ctreeSQL/part/name?top=3

Body:{
"advanced_find":{
"find_record": {
"operator": "=",
"fields":{
"part_name": "Part1",
"part_number": 1
}
}}
}

TOCIndex