💡User guide
Last updated
Last updated
This guide will rely on a couple example use cases that should make the concepts and functionality of AirQL more concrete and understandable.
Suppose that you keep a directory of employees in an Employees Airtable:
| Name | Favorite Pasta | Salary | |
|---|---|---|---|
It'd be useful to share access to this data with the team. The trouble is that the table also contains some sensitive personal information that shouldn't be shared. There are some workarounds using Airtable shared views or automations, but those are very course-grained and can be awkward to set up and use.
To address these limitations, AirQL provides you with an API based on your existing Airtables, and allows you to configure role-based permissions on a per-field basis.
In the example table above we could allow authenticated users to be able to access the Name, Email, and Pasta fields, but keep Salary data limited only to certain admins.
At a certain point in its growth, each company starts to start tracking employee time-off or vacation time. Here's a simple Airtable for tracking these requests:
| Start Date | End Date | |
|---|---|---|
Airtable makes it very easy to provide a form for employees to enter time-off requests using a form view. But it's not possible to allow employees to review or change their past requests without giving them full write access to the table.
AirQL allows you to configure row-level access control. For example, by giving each user access only to rows that match their AirQL login email.
To understand how we might build custom apps/workflows to support the above use cases, it's useful to dive into the details of how AirQL works:
Once you understand the above topics, come back to see how implementation for each example might work below.
Coming back to the motivating examples given above we'll briefly explain how we could support each use case using AirQL.
Create a user role and add all employees to that role.
Configure the Employees table for the user role, granting access to all fields except for the Salary field.
You can now build a simple dashboard that uses OAuth for authentication without having to give employees direct access to the Airtable or the API key.
Taking this a couple steps further, if you wished to grant managers access to salary information, you could create a second manager role with access to the Salary field.
Create a user role and add all employees to that role.
Configure the Time-off Requests table for the user role, granting access to all fields.
Use the filter formula {Email} = {AIRQL_USER_EMAIL} for the Time-off Requests table for the user role.
It's now possible to build OAuth app where employees can submit time-off requests, and they can review, modify and delete their own requests.
Supposing you then wished to provide managers an interface where they could see their reports' time off requests, you could so the following:
Add a Manager Email field to the table.
Create a manager role and add the appropriate users in AirQL
Configure the Time-off Requests table for the manager role, granting access to all fields.
Use the filter formula {Manager Email} = {AIRQL_USER_EMAIL} for the Time-off Requests table for the manager role.
For the manager view in the app, pass the header X-AirQL-Roles: manager.
For the user view in the app, pass the header X-AirQL-Roles: user.
Robert Seung
Spaghetti & meatballs
$105,000.00
Angela Walker
Penne arrabbiata
$140,000.00
Thea Dorian
Oatmeal
$82,600.00
2022-10-03
2022-10-03
2022-10-17
2022-10-21
2022-10-31
2022-10-31