Docs
Author:
Fluent Commerce staff
Changed on:
25 Oct 2023
Query operations are used for retrieving data. Fluent's GraphQL API provides two types of query operations:
`Get``Search`Query operations are used for retrieving data. Fluent's GraphQL API provides two types of query operations:
`Get``Search`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:
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`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`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 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.
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`Wildcard-based searching is performed using special characters.
`%``_`Examples
`%hn``%son%``_g``%s_n`Let's start with a simple search on customers and see how users can refine the search by using either of the following:
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]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]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]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]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]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]Search operations on LinkInput type fields allow users to query separate domains via a relational reference link.
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]The sorting is based on two attributes of the entity being queried and is in descending order.
Every search query (any GraphQL query that returns a
`<ENTITY_TYPE>Connection`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 |
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 |
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:
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.
