Fluent Commerce Logo
Docs
Sign In

GraphQL Queries

Essential knowledge

Author:

Fluent Commerce

Changed on:

25 Oct 2023

Overview

Query operations are used for retrieving data. Fluent's GraphQL API provides two types of query operations:

  • `Get`
    : To retrieve and display unique results
  • `Search`
    : To search and display a list of results

Key points

  • Get
  • Search
  • Pattern Based Searches
  • Search with Wildcard Characters
  • Performing Pattern-Based Searches
  • DateTime Search Operations
  • Link-Based Query Searches
  • Default Sort Order for Query Results
  • GraphQL Error Handling

Queries

Query operations are used for retrieving data. Fluent's GraphQL API provides two types of query operations:

  • `Get`
    : To retrieve and display unique results
  • `Search`
    : To search and display a list of results

Get

Get operations are used to fetch a single unique result. Every entity has a Get operation. Get operations have mandatory parameters as it is required to uniquely fetch an object. Some objects are accessible by ‘_ID_’, some by ‘_Ref_’ and others by a combination of keys.

To find a Get operation for an entity, simply type in its name into the schema documentation. The user will see one of the three options:

Get by ID:

If an object is accessible by an ID, it's Get operation will be 

`“<<entity>>ById(<<ID>>): <<entity>>”`
.

For instance, an Order can be retrieved by ID. So the Get operation is 

`orderById(id: ID!): Order`

Get by Ref:

If an object is accessible by a Ref, it's Get operation will be 

`“<<entity>>(<<ref>>): <<entity>>”`
.

For instance, a ProductCatalog can be retrieved by it's Ref. So the Get operation is:

`productCatalogue(ref: String!): ProductCatalogue`

Get by Keys:

If an object is accessible by a combination of fields that form a composite key, it's Get operation will be 

`“<<entity>>(<<key1>>,<<key2>>, <<key3>>,...): <<entity>>”`
.

For instance, an InventoryQuantity can be retrieved by a combination of it's ref and it's catalogs ref. So the Get operation is:

`inventoryQuantity(ref: String!, catalogue: InventoryCatalogueKey!): InventoryQuantity`


Search

Search operations return a list of results and they do not have any mandatory parameters. However, they support multiple optional parameters. If no parameters are passed, the Search operation retrieves all data for a given type. The number of results, however, would be capped at 10.

Search operations follow a fixed naming convention which is 

`“<<entity>>s(...)"`
. For example, Search operation on Order is, 
`orders(...)`
. To find a Search operation for an entity, type its name in the plural form.

`orders(...): OrderConnection`

Search operations return a list of results as Connections which is based on the relay specifications.


Pattern Based Searches

Searches support case in-sensitive and wildcard based comparisons. This provides better and more convenient search options for users in situations where the exact values may not be available or known.

Pattern-based searching is available by default and will apply to all 

`String`
 based fields.


Search with Wildcard Characters

Wildcard-based searching is performed using special characters.

  • `%`
    : Matches one or more characters
  • `_`
    : Matches a single character

Examples

  • `%hn`
    : Matches all values ending with "hn", Example: John, JOHN, john, kohn, abcedhn etc.
  • `%son%`
    : Matches all values with "son", Example: Robinson, sonder, consonance etc.
  • `_g`
    : Matches all values with three characters and the last character is g, Example: bag, sag, keg etc.
  • `%s_n`
    : Matches all values ending with "s" as the third last character and any character in the middle and ends with "n", Example: robinson, Davidson, prison, artisan etc.


Performing Pattern-Based Searches

Let's start with a simple search on customers and see how users can refine the search by using either of the following:

  • case insensitive searches.
  • wildcard based searches.

Simple Search

In the example below, no entity based parameters have been given and the search will return the earliest 10 customers, irrespective of their names.

 Simple Search

1query {
2    customers(last: 10) {
3    edges {
4        node {
5        id
6        timezone
7        lastName
8        firstName
9        primaryPhone
10        primaryEmail
11        createdOn
12        } 
13    }
14    }
15}

Language: graphqlschema

Name: Simple Search Example

Description:

[Warning: empty required content area]

Response

1{
2  "data": {
3    "customers": {
4      "edges": [
5        {
6          "node": {
7            "id": "744793",
8            "timezone": "Australia/Sydney",
9            "lastName": "Doe",
10            "firstName": "John",
11            "primaryPhone": "+123456789",
12            "primaryEmail": "jdoe@email.com",
13            "createdOn": "2016-03-08T00:50:26.000Z"
14          }
15        },
16        {
17          "node": {
18            "id": "738946",
19            "timezone": "Australia/Sydney",
20            "lastName": "Jack",
21            "firstName": "John",
22            "primaryPhone": null,
23            "primaryEmail": "jjack@email.com",
24            "createdOn": "2016-02-27T12:51:26.000Z"
25          }
26        },
27        {
28          "node": {
29            "id": "733235",
30            "timezone": "Australia/Sydney",
31            "lastName": "Rowe",
32            "firstName": "John",
33            "primaryPhone": "123456789",
34            "primaryEmail": "jr@email.com",
35            "createdOn": "2016-02-20T01:00:32.000Z"
36          }
37        },
38        {
39          "node": {
40            "id": "727818",
41            "timezone": "Australia/Sydney",
42            "lastName": "Foxx",
43            "firstName": "John",
44            "primaryPhone": "0412345678",
45            "primaryEmail": "jfoxx@email.com",
46            "createdOn": "2016-02-10T23:02:42.000Z"
47          }
48        },
49        {
50          "node": {
51            "id": "718348",
52            "timezone": "Australia/Sydney",
53            "lastName": "Robinson",
54            "firstName": "John",
55            "primaryPhone": null,
56            "primaryEmail": "johnrobinson@email.com",
57            "createdOn": "2016-01-27T06:30:44.000Z"
58          }
59        },
60        {
61          "node": {
62            "id": "718332",
63            "timezone": "Australia/Sydney",
64            "lastName": "Bouantoun",
65            "firstName": "John",
66            "primaryPhone": "012345678",
67            "primaryEmail": "johnb@email.com",
68            "createdOn": "2016-01-27T06:16:22.000Z"
69          }
70        },
71        {
72          "node": {
73            "id": "718331",
74            "timezone": "Australia/Sydney",
75            "lastName": "Bounty",
76            "firstName": "John",
77            "primaryPhone": "012345678",
78            "primaryEmail": "jbounty@email.com",
79            "createdOn": "2016-01-27T06:16:21.000Z"
80          }
81        },
82        {
83          "node": {
84            "id": "711894",
85            "timezone": "Australia/Sydney",
86            "lastName": "MILIONIS",
87            "firstName": "JOHN",
88            "primaryPhone": "123456789",
89            "primaryEmail": "jm@email.com",
90            "createdOn": "2016-01-23T05:25:13.000Z"
91          }
92        },
93        {
94          "node": {
95            "id": "711340",
96            "timezone": "Australia/Sydney",
97            "lastName": "Alessi",
98            "firstName": "John",
99            "primaryPhone": null,
100            "primaryEmail": "johna@email.com",
101            "createdOn": "2016-01-23T00:57:31.000Z"
102          }
103        },
104        {
105          "node": {
106            "id": "707671",
107            "timezone": "Australia/Sydney",
108            "lastName": "Bouantoun",
109            "firstName": "John",
110            "primaryPhone": null,
111            "primaryEmail": "jbouantoun@email.com",
112            "createdOn": "2016-01-20T02:04:57.000Z"
113          }
114        }
115      ]
116    }
117  }
118}

Language: json

Name: Simple Response Example

Description:

[Warning: empty required content area]

Search With Single Query Parameter

If searching for a specific customer with a known first name, clients are able to refine the search with this information in order to achieve more pertinent results.

In this example, the customer's first name is "John".

Search with single query parameter

1query {
2  customers(last: 10, firstName: "john") {
3    edges {
4        node {
5        id
6        timezone
7        lastName
8        firstName
9        primaryPhone
10        primaryEmail
11        createdOn
12      } 
13    }
14  }
15}

Language: graphqlschema

Name: Search Example

Description:

[Warning: empty required content area]

The response can have:

Response

1{
2  "data": {
3    "customers": {
4      "edges": [
5        {
6          "node": {
7            "id": "744793",
8            "timezone": "Australia/Sydney",
9            "lastName": "Doe",
10            "firstName": "John",
11            "primaryPhone": "+123456789",
12            "primaryEmail": "jdoe@email.com",
13            "createdOn": "2016-03-08T00:50:26.000Z"
14          }
15        },
16        {
17          "node": {
18            "id": "738946",
19            "timezone": "Australia/Sydney",
20            "lastName": "Hovelman",
21            "firstName": "John",
22            "primaryPhone": null,
23            "primaryEmail": "jhovelman@email.com",
24            "createdOn": "2016-02-27T12:51:26.000Z"
25          }
26        },
27        {
28          "node": {
29            "id": "733235",
30            "timezone": "Australia/Sydney",
31            "lastName": "Rowe",
32            "firstName": "John",
33            "primaryPhone": "0123456789",
34            "primaryEmail": "jrowe@email.com",
35            "createdOn": "2016-02-20T01:00:32.000Z"
36          }
37        },
38        {
39          "node": {
40            "id": "727818",
41            "timezone": "Australia/Sydney",
42            "lastName": "Man",
43            "firstName": "John",
44            "primaryPhone": "0123456789",
45            "primaryEmail": "jman@email.com",
46            "createdOn": "2016-02-10T23:02:42.000Z"
47          }
48        },
49        {
50          "node": {
51            "id": "718348",
52            "timezone": "Australia/Sydney",
53            "lastName": "Robinson",
54            "firstName": "John",
55            "primaryPhone": null,
56            "primaryEmail": "jrobinson@email.com",
57            "createdOn": "2016-01-27T06:30:44.000Z"
58          }
59        },
60        {
61          "node": {
62            "id": "718332",
63            "timezone": "Australia/Sydney",
64            "lastName": "Bouantoun",
65            "firstName": "John",
66            "primaryPhone": "012345678,
67            "primaryEmail": "jb@email.com",
68            "createdOn": "2016-01-27T06:16:22.000Z"
69          }
70        },
71        {
72          "node": {
73            "id": "718331",
74            "timezone": "Australia/Sydney",
75            "lastName": "Bouantoun",
76            "firstName": "JOHn",
77            "primaryPhone": "04 9 5249550",
78            "primaryEmail": "jb@email.com",
79            "createdOn": "2016-01-27T06:16:21.000Z"
80          }
81        },
82        {
83          "node": {
84            "id": "711894",
85            "timezone": "Australia/Sydney",
86            "lastName": "MILLIONS",
87            "firstName": "JOHN",
88            "primaryPhone": "0433933330",
89            "primaryEmail": "jmil@email.com,
90            "createdOn": "2016-01-23T05:25:13.000Z"
91          }
92        },
93        {
94          "node": {
95            "id": "711340",
96            "timezone": "Australia/Sydney",
97            "lastName": "Alex",
98            "firstName": "JoHn",
99            "primaryPhone": null,
100            "primaryEmail": "jalex@email.com",
101            "createdOn": "2016-01-23T00:57:31.000Z"
102          }
103        },
104        {
105          "node": {
106            "id": "707671",
107            "timezone": "Australia/Sydney",
108            "lastName": "Bounty,
109            "firstName": "JohN",
110            "primaryPhone": null,
111            "primaryEmail": "jbounty@email.com",
112            "createdOn": "2016-01-20T02:04:57.000Z"
113          }
114        }
115      ]
116    }
117  }
118}

Language: json

Name: Response Example

Description:

[Warning: empty required content area]

Search with Multiple Query Parameters

It is possible to further refine the above search by searching on multiple different fields.

In this example, the customer's first name is "John” and the last name begins with 'Robin'

Search with multiple query parameters

1query {
2  customers(last: 10, firstName: "john", lastName: "robin%") {
3    edges {
4        node {
5        id
6        timezone
7        lastName
8        firstName
9        primaryPhone
10        primaryEmail
11        createdOn
12      } 
13    }
14  }
15}

Language: graphqlschema

Name: Search Example

Description:

[Warning: empty required content area]

This search result will return all customers with the first name John and the last name beginning with ’Robin' .

Response

1{
2  "data": {
3    "customers": {
4      "edges": [
5        {
6          "node": {
7            "id": "718348",
8            "timezone": "Australia/Sydney",
9            "lastName": "Robinson",
10            "firstName": "John",
11            "primaryPhone": null,
12            "primaryEmail": "jrobs@email.com",
13            "createdOn": "2016-01-27T06:30:44.000Z"
14          }
15        }
16      ]
17    }
18  }
19}

Language: json

Name: Response Example

Description:

[Warning: empty required content area]

Queries can also be refined by passing multiple values for a given field. These can be specified in an array. For instance, to find customers with a first name starting with “_joh_” or ending with “_ti_”, the following queries can be used:

Search with multiple query parameter

1query {
2  customers(last: 10, firstName: ["joh%", "%ti"]) {
3    edges {
4        node {
5        id
6        timezone
7        lastName
8        firstName
9        primaryPhone
10        primaryEmail
11        createdOn
12      } 
13    }
14  }
15}

Language: graphqlschema

Name: Multiple Search Example

Description:

[Warning: empty required content area]

Results from the above query could be

Response

1{
2  "data": {
3    "customers": {
4      "edges": [
5        {
6          "node": {
7            "id": "744793",
8            "timezone": "Australia/Sydney",
9            "lastName": "Doe",
10            "firstName": "John",
11            "primaryPhone": "0123456789",
12            "primaryEmail": "jdoe@email.com",
13            "createdOn": "2016-03-08T00:50:26.000Z"
14          }
15        },
16        {
17          "node": {
18            "id": "738946",
19            "timezone": "Australia/Sydney",
20            "lastName": "Mason",
21            "firstName": "Joe",
22            "primaryPhone": null,
23            "primaryEmail": "joem@email.com",
24            "createdOn": "2016-02-27T12:51:26.000Z"
25          }
26        },
27        {
28          "node": {
29            "id": "733235",
30            "timezone": "Australia/Sydney",
31            "lastName": "Rowe",
32            "firstName": "Betti",
33            "primaryPhone": "012345678",
34            "primaryEmail": "browe@email.com",
35            "createdOn": "2016-02-20T01:00:32.000Z"
36          }
37        },
38        {
39          "node": {
40            "id": "727818",
41            "timezone": "Australia/Sydney",
42            "lastName": "Mando",
43            "firstName": "Ben",
44            "primaryPhone": "0413 405 559",
45            "primaryEmail": "bmendo@email.com,
46            "createdOn": "2016-02-10T23:02:42.000Z"
47          }
48        },
49        {
50          "node": {
51            "id": "718348",
52            "timezone": "Australia/Sydney",
53            "lastName": "Kumar",
54            "firstName": "Alice",
55            "primaryPhone": null,
56            "primaryEmail": "kalice@email.com",
57            "createdOn": "2016-01-27T06:30:44.000Z"
58          }
59        },
60        {
61          "node": {
62            "id": "711894",
63            "timezone": "Australia/Sydney",
64            "lastName": "MILLIONS",
65            "firstName": "JOHN",
66            "primaryPhone": "0433933330",
67            "primaryEmail": "jmillions@email.com",
68            "createdOn": "2016-01-23T05:25:13.000Z"
69          }
70        },
71        {
72          "node": {
73            "id": "711340",
74            "timezone": "Australia/Sydney",
75            "lastName": "Alex",
76            "firstName": "JoHn",
77            "primaryPhone": null,
78            "primaryEmail": "jalex@email.com",
79            "createdOn": "2016-01-23T00:57:31.000Z"
80          }
81        },
82        {
83          "node": {
84            "id": "707671",
85            "timezone": "Australia/Sydney",
86            "lastName": "Bounty",
87            "firstName": "JohNNy",
88            "primaryPhone": null,
89            "primaryEmail": "jbounty@email.com",
90            "createdOn": "2016-01-20T02:04:57.000Z"
91          }
92        }
93      ]
94    }
95  }
96}

Language: json

Name: Response Example

Description:

[Warning: empty required content area]


DateTime Search Operations

Search operations on DateTime type fields allow clients to query entities within GraphQL by using the date and time fields so as to generate date reports for a specific date or time period.

Below is a sample search query:

1#
2type DateRange {
3  # `DateTime` in UTC format for identifying records _after_ or _at_ the given timestamp.
4  from: DateTime
5  # `DateTime` in UTC format for identifying records _before_ or _at_ the given timestamp.
6  to: DateTime
7}
8
9# Settings Query
10settings(
11    # The unique setting id assigned by Fluent
12    id: ID,
13    ... # Other types. Not relevant #
14
15    createdOn: DateRange,
16    updatedOn: DateRange,
17
18    ... # Other types. Not relevant #
19): SettingConnection

Language: java

Name: Sample Search Query Example

Description:

[Warning: empty required content area]

Example Query - Past 15-minute query

In this example, the client requires an export of product data updated within the past 15 minutes. The current time for this example is 2018-03-27T17:20:00+00:00

Example: Specific time period query

1products(updatedOn: {from: '2018-03-27T17:20:00+00:00', to: '2018-03-27T17:35:00+00:00'})

Language: java

Name: Specific time period query Example

Description:

[Warning: empty required content area]

Example Query - Time period after a specific date 

In this example, the client requires a report of all orders that have come through after the boxing day sale is finished.

Example: Query after a specific date

1orders(createdOn: {from: '2017-12-27'})

Language: java

Name: Query after a specific date Example

Description:

[Warning: empty required content area]


Link-Based Query Searches

Search operations on LinkInput type fields allow users to query separate domains via a relational reference link.

Example Query - Search Return Order from Order

1query
2{
3    returnOrders(order: {ref:"gXjyWX", retailer: {id:   1}}) {
4edges {
5node {
6    ref
7    type
8    customer {
9  ref
10}
11order{
12  ref
13  retailer{
14    id
15  }
16}
17returnOrderItems{
18  edges{
19    node{
20      ref
21      product{
22        ref
23      }
24      orderItem{
25        ref
26        order{
27          ref
28        }
29      }
30
31                }
32             }
33     }
34     }
35        }
36            }

Language: graphqlschema

Name: Search Return Order from Order Example

Description:

[Warning: empty required content area]


Default Sort Order for Query Results

The sorting is based on two attributes of the entity being queried and is in descending order.

  • Created on the date and time of the entity
  • Database primary key identifier of the entity

Every search query (any GraphQL query that returns a 

`<ENTITY_TYPE>Connection`
) will use the above two fields in the same order to sort results. This means that the data is first sorted on the created-on value of the entity and then on the value of the primary key.

Result sorting example - non-UUID type

id

created on

4

2016-07-15 12:18:25.371000

3

2016-07-15 12:16:18.817000

2

2016-07-15 12:11:25.780000

1

2016-07-15 12:11:25.780000

Result sorting example - UUID type

id

created on

idcreated-one5899cd9-7138-4368-b6d0-2a01183a71f0

2018-04-09 07:07:47.891000

f7bd7a7d-52c6-4d45-be68-7bed1b4ee4e2

2018-04-09 07:06:17.006000

fe888de9-db5a-40ca-a83a-a4a3da959d06

2018-04-09 07:06:17.000000

f1d20e27-d3d0-4749-a2a5-efc39d084c1b

2018-04-09 07:06:17.000000


GraphQL Error Handling

Error Code: C0001E

Description: Indicates that a GraphQL query was made with higher complexity than is allowed by the server.

Possible workarounds: User is requested to reduce the complexity of the query and try again. The complexity of a query can be reduced by one or all of the following:

  • Reducing the nesting within the query
  • Reducing the requested fields within the query
  • Reducing the number of records requested within the query
Fluent Commerce

Fluent Commerce

Copyright © 2024 Fluent Retail Pty Ltd (trading as Fluent Commerce). All rights reserved. No materials on this docs.fluentcommerce.com site may be used in any way and/or for any purpose without prior written authorisation from Fluent Commerce. Current customers and partners shall use these materials strictly in accordance with the terms and conditions of their written agreements with Fluent Commerce or its affiliates.

Fluent Logo