Discover and import live tables with a paired agent

Agent discover-and-import reads live schema metadata directly from your source database through a paired local agent and imports the tables you choose into your DeltaVault workspace. No SQL queries to run by hand and no files to prepare.

Prerequisites

Before starting, confirm that both of the following are in place:

• A verified connection. The source connection must show a Verified status. Open the connection in DeltaVault and click Verify if it has not been verified yet. Verification runs through the local agent.
• An online local agent. The local agent must be installed, paired, and showing as online. If the connection screen reads “No DeltaVault Agent is online”, see the agent setup guide before continuing.

Start discovery

1. Open the workspace where you want to import. Its Details tab carries the Import metadata action; you will also find it on the workspace Catalog page, and on a project’s Details and Workspaces tabs.
2. Click Import metadata.
3. In the Import metadata dialog, choose Agent discovery. On a verified database connection this option is selected by default.
4. Click Next.

DeltaVault sends the discovery request to the local agent and transitions to the discovery screen.

Pick a database

Discovery parks on a database choice before it lists anything else. While the agent reads the server the screen says Listing databases…, then a page titled Select a database to import from offers what it found. Pick one and continue.

Two outcomes are worth recognizing. If the agent could not list the server at all, the screen names the error rather than sending you to fix permissions that may be fine. If it listed the server successfully but the connection’s login can open none of its databases, it says so and offers a refresh: grant the login access, or set the Database field on the connection, then refresh in place rather than starting the import again.

Discovery progress

With a database chosen, the screen shows Listing schemas… while the agent reads schemas and object lists from the source. This fast pass covers all schemas and objects in that database: it takes seconds even on a large one. The screen updates automatically when discovery finishes and the table selection tree appears.

Select tables

When discovery completes, the screen shows a tree of every schema and object found on the source. Use this screen to choose what to import.

• Search box. Type any part of a schema or table name to narrow the tree, prompted Search tables…. The filter applies immediately; clear it by emptying the box. A search that matches a great many objects shows the first two hundred and tells you to refine it.
• Hide views toggle. Turn on Hide views to show only base tables and remove views from the list.
• Clear. Unchecks everything. There is no Select all: a tree of every object on a database is not something to tick wholesale, so selection is deliberate.
• Selection count. The toolbar reads the running count, for example “12 selected”.
• Schema checkboxes. Checking a schema row selects all objects under it. Unchecking it clears them. Checking individual objects within a schema puts the schema into a partial state.

When your selection is ready, click Import N tables (where N is the count of selected objects). DeltaVault begins the import run.

Working with large databases

On a database with a large number of schemas or tables, DeltaVault keeps the selection screen usable by loading content in stages. The schema list appears first, so you can start reviewing and selecting straight away without waiting for every table to load.

Tables for each schema load on demand: they appear when you open (expand) a schema row or check it. Checking a schema selects all of its tables, and you can then uncheck individual tables to refine the selection. You do not need to expand a schema just to select everything under it.

The search box at the top of the tree finds tables by name across the whole database, not just the schemas you have already opened. Type any part of a table name and DeltaVault fetches matching results from the source. If the result set is very large, the screen notes that only the top matches are shown; narrow the search term to see more specific results.

Review and complete

After the import run finishes, the review grid opens automatically. It groups every object by functional layer: Source, Landing, Stage, and Persistent Stage. Each row is chipped Added, Changed, Removed, or Unchanged so you can see exactly what this import will write to the catalog.

When the review looks correct, click Complete import. DeltaVault commits all layers to your current branch. The result is branch-scoped, so you can review, revert, or compare it through the usual branch workflow before merging.

See Review an import for a full walkthrough of the review grid and the generated layers canvas.