Search docs.molo17.com
    Operational guide Control Plane

    Query pipeline data with Query Studio and control who can access it

    Query Studio is the SQL workbench built into the Control Plane. Use it to check what a pipeline has replicated, to answer a quick question about the data, and to fix a row in a scratch table, without leaving Gluesync. Because it reaches real databases, it also has its own access rules: this guide shows both how to query and how a Super Admin decides who can query what.

    In this guide

    You will learn how to open Query Studio on a pipeline connection, browse its schemas, run a filter, a join, and an aggregate on shop.customers and shop.orders, sort, page, chart, export, and save the results, and edit rows in a scratch table. Then you will see how personal data is masked, restrict a Viewer to one table, let a Manager unmask personal data, and confine a Manager who can write to one scratch schema.

    Quick information

    Goal

    Query pipeline data safely in Query Studio and control which users can query which tables

    Audience

    Data engineers and Gluesync administrators

    Level

    Intermediate

    Time required

    About 40 minutes

    Area

    Control Plane → Query Studio, and Settings → Query data access

    Applies to

    Gluesync 2.3

    Before you begin

    Make sure that:

    1. A pipeline already has a PostgreSQL source and a PostgreSQL target, for example the connections Shop orders-source and Shop orders-target;

    2. The source database has the tables shop.customers and shop.orders. For the editing step you also need a table you can safely change; if you do not have one, the guide shows how to create a scratch table in the target database;

    3. You can sign in to the Control Plane as a Super Admin;

    4. For the access steps, you have two users: a Viewer and a Manager (the examples use qs-viewer and qs-analyst), and a second browser, or a private window, in which to sign in as them.

    Query Studio uses the database credentials of the agent, on a connection of its own that is separate from the replication. In this guide every change is made in the table shop_qs.notes in the target database, never in shop.customers or shop.orders, and no pipeline is started, stopped, or edited.

    Guide steps

    Open Query Studio and choose a connection

    UI

    1. Select Query Studio (the SQL icon) in the left sidebar;

    2. Select the + next to the session tabs to open a new session;

    3. Open the SQL-capable Agent list, select the pipeline Shop orders, and then select Shop orders-source (SOURCE).

    SQL-capable Agent list with the pipeline Shop orders marked 1 and the agent Shop orders-source marked 2
    Figure 1. The list shows pipelines on the left (1) and the SQL-capable agents of the selected pipeline on the right (2).

    The workspace opens with the schema browser on the left, the SQL editor in the middle, and the result tabs below the editor.

    Query Studio workspace with the agent list marked 1
    Figure 2. The agent (1), the schema browser (2), the SQL editor and toolbar (3), and the result tabs (4).
    Expected result

    The tab shows the agent name, and the schema browser lists the schemas of the source database, such as shop. Read-only is switched on, and so is PII masked, in the toolbar.

    Only SQL-capable agents are listed. Query Studio opens one session per agent, so you can keep the source and the target open side by side in separate session tabs.

    Browse schemas, tables, and columns

    UI

    1. In the schema browser, expand the shop schema;

    2. Select customers to list its columns with their types, primary key, and personal data tags;

    3. Select the three-dot menu next to customers to see the table actions.

    Schema browser with the customers table marked 1 and the PII:name and PII:email tags on its columns marked 2
    Figure 3. Columns show their type, the primary key, and a PII tag when Core Hub classified them (1, 2).
    Table actions menu with SELECT * FROM shop.customers marked 1 and Scan table for PII marked 2
    Figure 4. The table menu starts a query (1) and can scan the table for personal data (2).
    Expected result

    customers expands to id (the key), full_name, email, country, tier, status, credit_limit, and created_at. full_name and email carry the tags PII:name and PII:email. Selecting a table also opens a query tab with a SELECT * on it and runs it.

    The table menu also copies the table name, the qualified name, or the schema name, copies or generates a CREATE TABLE statement, imports data, and refreshes the columns. The search box above the tree filters schemas by name, and the tables of the schemas you have expanded.

    Run a filter, a join, and an aggregate

    UI

    Query Studio runs the statement in the active editor tab. Run each of the three queries that follow in turn: select all text in the editor, paste the statement, and select Run (or press Ctrl+Enter, Cmd+Enter on macOS).

    A filter. Which active Italian customers have the highest credit limit?

    SELECT id, country, tier, status, credit_limit
    FROM shop.customers
    WHERE country = 'IT' AND status = 'active'
    ORDER BY credit_limit DESC
    Editor with the filter query marked 1
    Figure 5. The editor (1), the Run button (2), and the status line with the row count (3).

    A join. Which paid orders belong to platinum customers?

    SELECT c.id AS customer_id, c.country, o.id AS order_id, o.amount, o.currency, o.status
    FROM shop.customers c
    JOIN shop.orders o ON o.customer_id = c.id
    WHERE c.tier = 'platinum' AND o.status = 'paid'
    ORDER BY o.amount DESC
    Result grid of the join query with 50 rows ordered by amount
    Figure 6. The join returns 50 rows, highest amount first.

    An aggregate. How much revenue does each country and currency bring in, excluding cancelled orders?

    SELECT c.country, o.currency, COUNT(*) AS orders, SUM(o.amount) AS revenue
    FROM shop.orders o
    JOIN shop.customers c ON c.id = o.customer_id
    WHERE o.status <> 'cancelled'
    GROUP BY c.country, o.currency
    ORDER BY revenue DESC
    Result grid of the aggregate query with 24 rows
    Figure 7. The aggregate returns 24 rows, one for each country and currency pair.
    Expected result

    The status line shows Completed and the number of rows and the run time: 20 rows for the filter, 50 for the join, and 24 for the aggregate. The first row of the aggregate is IT, GBP, 33 orders, revenue 36495.00.

    Read-only is on by default, so Query Studio refuses statements that change data. Format SQL in the toolbar rewrites the statement with one clause on each line and upper-case keywords. Explain shows the execution plan of the statement.

    Sort, search, page, and inspect the result

    UI

    1. Select a column header, for example revenue, to sort the result by that column; select it again to reverse the order;

    2. Select the magnifier icon above the grid and type a word, for example GBP, to keep only the rows that contain it, or select the funnel in a column header to tick the values of that column to keep;

    3. Select the record icon at the right of the grid toolbar to read one row as a list of fields;

    4. Select the Stats tab to see the minimum, maximum, and mean of numbers and the length and unique count of text for each column.

    Result grid sorted by revenue with the revenue header marked 1
    Figure 8. Sorting by revenue (1), searching the rows (2), and the record view (3).
    Stats tab with one card per column of the aggregate result
    Figure 9. The Stats tab summarizes each returned column.

    Large results arrive in batches. Run SELECT id, customer_id, amount, currency, status, order_date FROM shop.orders ORDER BY id: Query Studio shows the first 200 of the 1,000 rows and marks the result Truncated. Use the arrows in the grid toolbar to fetch the next rows.

    Orders result showing rows 201 to 400
    Figure 10. The status line shows Truncated and 200 rows (1). The arrows fetch the next batch (2).
    Expected result

    Sorting reorders the rows in the grid, and a second click reverses the order. After you select the next-page arrow, the toolbar shows 201–400 and the grid shows orders 201 onward.

    Chart a result

    UI

    1. Run the aggregate query again;

    2. Select the Chart tab;

    3. Select Bar, Line, or Pie;

    4. Pick the Label column and the Value column, for example country and revenue.

    Chart tab with the Bar
    Figure 11. Choose the chart type (1) and the columns it plots (2).
    Expected result

    The tab draws a bar chart titled revenue by country.

    The Chart tab charts one result for yourself. For prompt-driven charts and dashboards built from your connected data, see Visualize.

    Export or copy a result

    UI

    1. Select Export in the toolbar and choose Export CSV, Export XLSX, or Export JSON to download the result;

    2. Or select Copy result and choose Copy as CSV, Copy as JSON, Copy as Markdown, Copy as HTML, Copy as XML, or Copy as INSERT… to put it on the clipboard.

    Export menu with the options Export CSV
    Figure 12. Export downloads a file (1).
    Copy result menu with the options Copy as CSV
    Figure 13. Copy result offers six formats (1).
    Expected result

    Export CSV downloads query-result.csv. Copy shows a confirmation such as Copied as CSV. in the corner of the screen.

    Exports and copies carry the masked values, not the originals. When you export the customer list with PII masked on, the file contains only the unclassified columns (id, country, and tier in the example of this guide). See See how personal data is masked.

    Save a query and find it again

    UI

    1. Run the aggregate query;

    2. Select Save query in the toolbar;

    3. Enter Query name Revenue per country and currency, an optional Description, and an optional Folder;

    4. Under Who can see this query, keep Personal (only me);

    5. Select Save;

    6. Select Saved queries to list your queries, and Query history to open the History tab.

    Save Query dialog with the Query name marked 1
    Figure 14. Name the query (1), file it in a folder (2), choose who can see it (3), and save (4).
    Saved Queries list showing the Revenue per country and currency query as Personal in the folder How-to guides
    Figure 15. The saved query is listed with its scope, folder, pipeline, and last run (1).
    History tab listing the executed statements with their status
    Figure 16. Every run is recorded with its time, status, rows, and duration (1).
    Expected result

    Query saved. appears, the editor tab takes the name of the query, and the query is listed under Saved queries. History shows each statement you ran with its status (COMPLETED or TRUNCATED), row count, and duration in milliseconds. Session feed lists only the queries run in the current session.

    Next to each saved query, the three-dot menu offers Edit, View history, and Delete. Instead of Personal (only me), choose Pipeline (anyone with access to this pipeline) or Team (anyone who can manage saved queries) to share a query. A saved query can also run on a schedule: see Query Studio actions.

    Ask Spark for help writing SQL

    UI

    1. Select the round launcher at the bottom right of the editor;

    2. Read the panel Spark in Query Studio.

    Spark in Query Studio panel above the editor with the launcher marked 1 and the Connect an LLM provider button marked 2
    Figure 17. The launcher (1) opens Spark. Until a Super Admin connects a model provider, the panel offers Connect an LLM provider (2).
    Expected result

    Without a model provider, the panel explains that Spark needs one. A Super Admin sees Connect an LLM provider, a Manager sees Open LLM provider settings, and a Viewer is told to ask a super administrator.

    This guide does not configure a model provider. To set one up and to learn what Spark can do, see AI models and LLM providers and Query Studio AI helper.

    Edit data in a table you can safely change

    UI

    Do this on a table that you are allowed to change, never on the tables that a pipeline replicates. The example uses the table shop_qs.notes in the target database.

    1. Open a new session and select Shop orders-target (TARGET);

    2. Switch the Read-only toggle to Writable. A banner warns that destructive queries run against the database;

    3. Optional: if you do not already have a table you can safely change, create a scratch one. Run each of these statements in turn:

      CREATE SCHEMA IF NOT EXISTS shop_qs
      CREATE TABLE IF NOT EXISTS shop_qs.notes (id integer PRIMARY KEY, topic text NOT NULL, note text, created_at timestamp DEFAULT now())
      INSERT INTO shop_qs.notes (id, topic, note) VALUES (1, 'access', 'Policies are per user and per connection'), (2, 'export', 'CSV, XLSX and JSON downloads'), (3, 'history', 'Every run is recorded')
    4. Run SELECT * FROM shop_qs.notes ORDER BY id;

    5. Double-click the note cell of row 3, type Every run is recorded in History, and press Enter;

    6. Select the eye icon in the grid toolbar to review the pending change, and then select Save changes.

    Toolbar in Writable mode with the Tx
    Figure 18. Writable mode shows a warning (1) and the Tx setting for transactions (2).
    Result grid of shop_qs.notes with the edited note cell marked 1 and the save
    Figure 19. A staged cell edit (1). The save, review, and record icons are at the right of the toolbar (2).
    Pending cell changes dialog showing Row 3
    Figure 20. The review dialog shows the old and the new value before anything is written.
    Expected result

    1 change(s) saved and committed. appears, and the cell shows the new text. Reading the table from another client returns the same value. The grid is editable only when the result comes from a single table with a primary key; the message Cell editing is disabled in read-only mode. Switch to Writable to edit a single-table result. appears while Read-only is on.

    Writable mode runs statements directly against the database. With Tx: Auto, each statement commits as soon as it runs. Switch back to Read-only when you finish.

    See how personal data is masked

    UI

    Query Studio hides the values of columns that Core Hub classified as personal data.

    1. Select the source session tab;

    2. Run SELECT id, full_name, email, country, tier FROM shop.customers ORDER BY id;

    3. Look at the full_name and email columns;

    4. As a Super Admin, switch PII masked to PII visible and run the query again.

    Customer result with the PII tags in the headers marked 1
    Figure 21. The PII tags (1) mark the columns whose values are masked (2) while PII masked is on (3).
    Customer result with the PII visible toggle marked 1 and the full names and e-mail addresses shown in clear
    Figure 22. With PII visible on (1), the same query returns the original values (2).
    Expected result

    With PII masked on, names appear as •••• and e-mail addresses as c***@***.com. With PII visible on, the original values appear.

    Masking is applied by Core Hub before the result reaches your browser. The PII visible switch is shown only to roles that may unmask data, and even then Core Hub unmasks only when the user has been granted it: see Let a Manager unmask personal data. For the full list of labels and how classification works, see PII discovery and masking.

    Open Query data access

    UI

    Only a Super Admin sets who can query what. Policies are set per user and per connection.

    1. In Query Studio, select the shield icon Manage query data access next to the agent list;

    2. In Applies to, keep User;

    3. In User, select the user to configure, for example qs-viewer;

    4. In Connection, select the database connection to configure, for example Shop orders-source.

    Query Studio toolbar with the Manage query data access shield icon marked 1
    Figure 23. The shield icon opens Query data access.
    Query data access settings with Applies to marked 1
    Figure 24. Choose whether the policy applies to a user or a group (1), the user (2), the connection (3), and an optional template (4).
    Expected result

    Settings → Query data access opens with the matrix of that user on that connection. A user without a policy is Open: nothing is restricted.

    A Manager or a Viewer does not see the shield icon. The same screen has a User group switch to give one policy to several users at once: see Manage users, groups, and roles in Gluesync.

    Restrict a Viewer to one table

    UI

    1. With qs-viewer and Shop orders-source selected, set Connection mode to Restricted;

    2. Select Add rule, enter Schema shop and Table (optional, * for all) orders, and switch Allow on;

    3. Select Save policy;

    4. In the second browser, sign in as qs-viewer and open Query Studio on Shop orders-source;

    5. Expand the shop schema;

    6. Run SELECT id, customer_id, amount, currency, status FROM shop.orders WHERE status = 'paid' ORDER BY amount DESC;

    7. Run SELECT c.country, o.currency, SUM(o.amount) AS revenue FROM shop.orders o JOIN shop.customers c ON c.id = o.customer_id GROUP BY c.country, o.currency.

    Query data access rules with the Restricted mode marked 1
    Figure 25. Restricted mode (1), a rule that allows shop.orders (2), the PII unmask grants (3), and Save policy (4).
    Query Studio as qs-viewer
    Figure 26. The Viewer sees only orders in the shop schema (1) and has no PII switch (2).
    Errors tab as qs-viewer showing the message Access denied to shop.customers
    Figure 27. A query that touches shop.customers is refused (1).
    Expected result

    Data access policy saved appears. For qs-viewer, the schema browser lists only orders, the first query returns the paid orders, and the join fails with Access denied to shop.customers.

    Query Studio shows an access refusal under the heading Read-only query rejected. The line that matters is Access denied to <schema>.<table>. System schemas such as information_schema and pg_catalog stay listed.

    Two other patterns work with the same screen. Keep Open and add a rule with Allow switched off to deny one sensitive table (a denial always wins), or use Restricted and allow whole schemas by entering * as the table.

    Confirm that a Viewer cannot write

    UI

    1. As qs-viewer, open a session on Shop orders-target (TARGET);

    2. Switch Read-only to Writable;

    3. Run UPDATE shop_qs.notes SET note = 'changed by qs-viewer' WHERE id = 1.

    Writable mode as qs-viewer with the toggle marked 1 and the error Role VIEWER does not have canRunQueryWritable permission marked 2
    Figure 28. The toggle can be switched (1), but Core Hub refuses the statement (2).
    Expected result

    The Errors tab shows Role VIEWER does not have canRunQueryWritable permission, and the row id = 1 in shop_qs.notes keeps its old text. The role, not the toggle, decides who can write.

    Let a Manager unmask personal data

    UI

    A Manager can switch PII visible on, but Core Hub unmasks only the data the user has been granted.

    1. As qs-analyst (a Manager), open Query Studio on Shop orders-source;

    2. Switch PII masked to PII visible;

    3. Run SELECT id, full_name, email, country, tier FROM shop.customers ORDER BY id.

    4. As a Super Admin, open Settings → Query data access, select qs-analyst and the connection Shop orders-source, choose the template MANAGER (read-only default), and select Apply template;

    5. As qs-analyst, reload Query Studio, switch PII visible on, and run the query again.

    Customer result as qs-analyst with the PII visible toggle marked 1 and the full_name and email values still masked
    Figure 29. The switch is on (1), but without a grant the values stay masked (2).
    Query data access for qs-analyst with the MANAGER template and Apply template button marked 1 and the empty PII unmask grant row marked 2
    Figure 30. The MANAGER template (1) leaves the connection open and adds a grant for all schemas, tables, and columns (2).
    Customer result as qs-analyst with the PII visible toggle marked 1 and the clear full names and e-mail addresses marked 2
    Figure 31. After the grant, the same switch shows the original values (2).
    Expected result

    Before the grant, the query returns •••• and c***@***.com even though PII visible is on. Template applied to this user appears when you apply the template, and afterwards the query returns the original names and e-mail addresses.

    Apply template copies the template to every connection that has one and replaces the policies of the user on all of them. If qs-analyst was already restricted on another connection, that restriction is lost. Apply the template first, then set the connection-specific rules, as the next step does. To grant unmasking for one schema, table, or column only, use Add unmask grant instead.

    Confine a Manager to a scratch schema

    UI

    1. As a Super Admin, select qs-analyst and the connection Shop orders-target;

    2. Set Connection mode to Restricted;

    3. Select Add rule, enter shop_qs in Schema and * (all tables) in the Table field, and switch Allow on;

    4. If the matrix contains an empty PII unmask grants row, delete it, and select Save policy;

    5. As qs-analyst, open a session on Shop orders-target (TARGET);

    6. Run SELECT * FROM shop_qs.notes ORDER BY id;

    7. Run SELECT * FROM shop.customers LIMIT 5.

    Query data access for qs-analyst on Shop orders-target with Restricted marked 1 and the Allow rule for schema shop_qs and table * marked 2
    Figure 32. Restricted mode (1) and a rule that allows every table of shop_qs (2).
    Query Studio as qs-analyst on the target where the schema browser lists information_schema
    Figure 33. The Manager sees only shop_qs (1) and can read the scratch table.
    Errors tab as qs-analyst showing Access denied to shop.customers
    Figure 34. Any other table is refused (1, 2).
    Expected result

    qs-analyst can read and, in Writable mode, change shop_qs.notes, and the query on shop.customers fails with Access denied to shop.customers. The same Manager keeps the grant to unmask data on Shop orders-source.

    Who can do what in Query Studio

    A user’s role sets the ceiling. A Query data access policy then narrows what that role can reach on each connection.

    Capability Super Admin Manager Viewer

    Open Query Studio and run read-only SQL

    Yes

    Yes

    Yes

    Switch to Writable and run SQL that changes data

    Yes

    Yes

    No: Role VIEWER does not have canRunQueryWritable permission

    See the PII visible switch

    Yes

    Yes

    No

    Unmask personal data

    Always

    Only with an unmask grant

    Never

    Open Query data access

    Yes

    No

    No

    Is limited by Query data access rules

    No

    Yes

    Yes

    How a policy is applied:

    • A user without a policy on a connection is not restricted there. Policies are per user and per connection.

    • Restricted allows only the schemas and tables you add with Allow on. Open allows everything except what you deny.

    • A denial always wins over an allow. A schema-wide rule has no table, or * as the table.

    • System schemas such as information_schema and pg_catalog stay reachable.

    • The Query data access screen states that its rules and grants cover Query Studio, AI SQL, and the Spark query tools, not only the editor.

    Where Query Forge fits

    Query Studio queries one agent at a time. Query Forge, in the left sidebar, is the federated, read-only SQL endpoint for BI tools and external JDBC clients; it works with Personal API Tokens scoped to pipelines and agents. This guide does not set it up. See Query Forge and Personal API tokens.

    Verify the result

    You have successfully queried the data and restricted access if:

    • The filter, join, and aggregate queries return 20, 50, and 24 rows on the seeded Shop orders-source data;

    • A result can be sorted, charted, exported, and found again in Saved queries and History;

    • shop_qs.notes in the target shows your edited note, and shop.customers and shop.orders are unchanged;

    • full_name and email are masked until an authorized user switches on PII visible;

    • qs-viewer can query shop.orders only and cannot write;

    • qs-analyst can unmask personal data on the source and can reach only shop_qs on the target.

    Troubleshooting

    Problem Possible cause What to do

    A schema or table is missing from the schema browser

    A Restricted policy, or a deny rule, hides it from your user

    Ask a Super Admin to check your policy for that connection in Settings → Query data access

    Read-only query rejected with Access denied to schema.table

    The rule matched a table that your policy does not allow; the heading is shown for every refusal

    Read the second line. If it names a table, ask a Super Admin to add an Allow rule

    PII visible is on but values are masked

    Your user has no unmask grant, or your role cannot unmask

    Ask a Super Admin for an unmask grant; a Viewer can never unmask

    Role VIEWER does not have canRunQueryWritable permission

    Your role cannot run SQL that changes data

    Use a Manager or a Super Admin account for writes

    Cell editing is disabled in read-only mode

    Read-only is on, or the result comes from more than one table

    Switch to Writable and run a SELECT on one table that has a primary key

    The result shows Truncated and 200 rows

    Results arrive in batches of 200 rows

    Select the next-page arrow in the grid toolbar

    A restriction on another connection disappeared after Apply template

    The template replaced all policies of the user

    Apply the template first, then set the connection-specific rules again

    Contact MOLO17 Support if you need assistance with Query Studio or its access rules.