GraphQL Examples

To fastrack your mastery of GraphQL, it is highly recommended that you read the schema documentation seen on the right side of the graphQL GUI editor (use: pos-cli gui serve [environment]). This documentation helps you see an overview as to what the functions and parameters you can use.

Having said that, there certainly is a limit to how much you can learn by reading the documentation - hands-on coding is still the best way to learn. A helpful tip while writing code: Maximize the auto-complete feature built-in on the graphQL GUI. While typing, press CTRL+Space on a PC or Option+Space in macOS. If nothing comes up on the selection, it means there’s something wrong on the previous line of code that needs to be changed.

Best Practices

• Always paginate your data. There is no hard limit on Insites’ data records per page, however the more data there is, the slower querying and processing will be.
• Utilise snake case for file names, form names, graphQL names, among others. Use dash-separated names for slugs or URLs.
• Use an ‘alias’ on your graphQL queries as there are different graphQL function names which will be part of your return data. By using a standard alias (For example: ‘items’ on the sample below), you can standardize your data processing on the front-end (specially for ‘query’ graphQL). Aliasing also helps shield the code if there’s a need to change your endpoint / graphQL (For example: platformOS new releases and/or breaking changes).

Example:

Query Examples

The following examples demonstrate GraphQL queries for operations such as listing, searching, and sorting. They are largely analogous to 'GET' and 'SELECT' operations.

1. Single Source - User

2. Single Source - Record

3. Filtering and Sorting - User

Important:

• As you nest your graphQL, this will behave as an AND statement.
• If you do not pass a parameter value, it will run the query and not consider the filter criteria the parameter was used (For example: In the example below, ‘email’ and ‘keyword’ can be used as independent or combined filter / search fields, or no filter at all if you don’t pass both fields)

4. Filtering and Sorting - Record

Notes:

• There are more filtering options that include: ‘starts_with’, ‘ends_with’, ‘not_starts_with’, ‘not_ends_with’, ‘contains’, ‘not_contains’, ‘value’, ‘exist’, etc. The options vary depending on the function / data being considered.
• Use the auto-complete feature and chose the best filter method as needed
• ‘contains’ will filter case insensitive (good for keyword search / elastic search).
• ‘value’ and other filter types filter as case sensitive (search specific data)

Important:

• As you nest your graphQL, this will behave as an AND statement.
• The order ‘DESC/ASC’ here is not a string (wrapped in “ “), this is a current inconsistency with the platform code.

5. Multi / Related Data

Insites functionality with regards to data relation is constantly evolving. This section contains some available examples.

Note:

Fields defined in the ‘join_on_property’ and ‘foreign_property’ can be anything defined under the data point it is being related to (Users / Records).

User to Record Data Relation

Record to Record Data Relation

record to User Data Relation

6. Filtering by Related Data

At this time of writing, this feature is still under development. Thus, no examples are available yet.

Mutation Examples

The following examples demonstrate GraphQL mutations for operations such as inserting, deleting, and updating data in the database.

1. Create User

2. Create Record

3. Update User

4. Update Record

5. Delete User

6. Delete Record

Important:

• To restore data, run an 'update' mutation, and set deleted_at to null.
• If a user is deleted, all its associated profiles and data will be deleted as well.
• Restoring a user does not restore associated profiles; each previously deleted profile needs to be restored individually.