GraphQL Queries
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:
- : To retrieve and display unique results
`Get` - : To search and display a list of results
`Search`
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:
- : To retrieve and display unique results
`Get` - : To search and display a list of results
`Search`
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(...)"``orders(...)``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`Search with Wildcard Characters
Wildcard-based searching is performed using special characters.
- : Matches one or more characters
`%` - : Matches a single character
`_`
Examples
- : Matches all values ending with "hn", Example: John, JOHN, john, kohn, abcedhn etc.
`%hn` - : Matches all values with "son", Example: Robinson, sonder, consonance etc.
`%son%` - : Matches all values with three characters and the last character is g, Example: bag, sag, keg etc.
`_g` - : 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.
`%s_n`
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): SettingConnectionLanguage: 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`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
