GraphQL Queries
Author:
Fluent Commerce
Changed on:
3 June 2025
Overview
Query operations are used for retrieving data. Fluent's 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 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 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 , 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 , 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 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}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}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 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}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}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}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}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}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}Advanced Customer Search in Orders Query
The `orders` search operation supports a powerful and unique customer filtering logic that is not available for other queries. This advanced filter uses the `SearchCustomerInput` input type, enabling flexible search capabilities tailored to complex use cases.
What makes it unique:
- Multiple customer fields can be used together in a single filter block (e.g.,
`firstName`,`lastName`,`username`, etc.) - Each field supports multiple values, matched using logical OR
- Different fields are combined using logical AND
- Multiple filter blocks can be passed in an array, allowing top-level OR logic
- Supports wildcard and case-insensitive pattern matching across all fields
This logic allows highly targeted searches like:
"Find all orders where the customer is John and their last name includes 'Doe', or the username is exactly 'j.smith'."
This level of control and expressiveness is currently exclusive to the `orders` query.
Search with advanced customer filter
1query {
2 orders(
3 first: 10,
4 customer: [
5 {
6 firstName: ["John", "Emma", "Alice"],
7 lastName: "%Doe%"
8 },
9 {
10 username: "j.smith"
11 }
12 ]
13 ) {
14 edges {
15 node {
16 id
17 ref
18 type
19 status
20 customer {
21 firstName
22 lastName
23 username
24 }
25 }
26 }
27 }
28}Response
1{
2 "data": {
3 "orders": {
4 "edges": [
5 {
6 "node": {
7 "id": "1488206",
8 "ref": "HD-ORDER-REF-743",
9 "type": "HD",
10 "status": "BOOKED",
11 "customer": {
12 "firstName": "John",
13 "lastName": "Doe",
14 "username": "john.doe"
15 }
16 }
17 },
18 {
19 "node": {
20 "id": "1488203",
21 "ref": "HD-ORDER-REF-5037",
22 "type": "HD",
23 "status": "COMPLETE",
24 "customer": {
25 "firstName": "Alice",
26 "lastName": "Doeman",
27 "username": "alice123"
28 }
29 }
30 },
31 {
32 "node": {
33 "id": "1488190",
34 "ref": "HD-ORDER-REF-8637",
35 "type": "HD",
36 "status": "COMPLETE",
37 "customer": {
38 "firstName": "Emma",
39 "lastName": "Doe",
40 "username": "emma.doe"
41 }
42 }
43 },
44 {
45 "node": {
46 "id": "1488185",
47 "ref": "HD-ORDER-REF-4455",
48 "type": "HD",
49 "status": "BOOKED",
50 "customer": {
51 "firstName": "Jane",
52 "lastName": "Smith",
53 "username": "j.smith"
54 }
55 }
56 }
57 ]
58 }
59 }
60}DateTime Search Operations
Search operations on DateTime type fields allow clients to query entities within 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): SettingConnectionExample 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'})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'})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 }Default Sort Order for Query Results
The sorting is based on two attributes of the being queried and is in descending .
- Created on the date and time of the entity
- Database primary key identifier of the entity
Every search query (any query that a `<ENTITY_TYPE>Connection`) will use the above two fields in the same to sort results. This means that the data is first sorted on the created-on value of the 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 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
