Skip to main content
TutorialApplies to: Unified engine deployments
Connect an existing catalog service, inspect a table, and run a query that reads its files. A catalog lists tables and their schemas. Table storage holds the actual data.

​
Before you start

Start with Secrets and Credentials for SQL examples that prepare your access resources. You need permission to register a catalog, an existing service endpoint, and access to at least one table. Ask the service owner for these values: The console does not create the remote service or grant cloud permissions. Use the connection types guide to match the provider. If a suitable connection already exists, start at step 3.

​
1. Enter the connection

  1. Open Catalogs and start a new connection.
  2. Give it a clear name, such as lesson_catalog, if that name is unused.
  3. Choose the connection type supplied by the service owner.
  4. Enter the required connection details. Use the catalog API endpoint, not its website address.
  5. Under Access, choose the authentication method and named credential.
  6. Set a separate storage credential only when file access needs one. Choose delegation only when the service supports it.
Use Create credential beside a credential field when you need a new saved credential. Follow the relevant credential guide. Do not paste secret values into a lesson or a query document.

​
2. Test and save

Select Test connection and inspect its result. Then select Connect catalog. Testing does not save the connection. Expect the saved connection to appear in Catalogs. This proves registration and the tested metadata access. The next steps check table access.

​
3. Inspect a real table

  1. Open the namespace supplied by the service owner.
  2. Select the test table and open Schema.
  3. Find the expected column and inspect its type.
  4. Use the table’s query action to open Workbench.
  5. Check the selected catalog and namespace before running.
Keep the table name generated by the query action. For a table named orders, a preview looks like this:
Replace orders if your test table has another name. Expect at most ten rows and columns matching its schema. For an empty table, use a known non-empty table to check actual file reads.

​
4. Check the full row count

In the same Workbench context, run:
Use your actual table name. Expect one row containing its count. The count depends on your data; there is no fixed lesson value. If the owner supplied a known count, compare it while the source is stable. The preview in step 3 also matters because some engines can answer counts from metadata.

​
Change one thing

Use a real column from Schema to narrow the preview. For example, if the table has a string column called region, add WHERE region = 'North' before LIMIT. Inspect the returned values and confirm that each row matches your filter. The column names and values must come from your table. Do not assume that a customer table has the six sample orders used in the other lessons.

​
Check the result

You can find the saved connection, browse the expected table, and read known data from it. A successful connection test alone is not enough to complete this lesson.

​
Clean up

Keep a shared connection in place. If you created a connection only for this lesson, first remove its saved-query consumers, then choose Unregister and confirm its name. Unregistering removes the registration, not the remote tables. Remove lesson-only credentials separately after checking their consumers.

​
Continue

Build a dashboard with the fixed sample data. Return to connection setup for provider fields and access options.
Last modified on November 4, 2026