SQL Search & Dependencies
Find text inside saved definitions, trace what an object uses and what uses it, and review the impact of changing a column.
Getting Started
- Open Tools → SQL Search & Dependencies in Studio, or find it in the command palette.
- Choose the active database and, when sharding is enabled, the route you want to inspect.
- Enter text such as a column name, narrow the results with the search options, and select a definition.
- Use Uses, Used by, or Graph to follow references. Select a column and open Impact to assess a proposed change.
Search and Navigation
Search matches plain text in object names and definition bodies. Use the object-type filter, Match case, and Whole word to narrow results. Comments and string literals are searchable; SQL dependency analysis does not treat them as references.
Results show highlighted excerpts and source positions. The preview provides match navigation and paged source text.
| View | What it shows |
|---|---|
| Definition | The stored source. Schema objects display catalog JSON; C# modules display their source text. |
| Uses | Outgoing references with the column, usage, confidence, and SQL statement location or JSON property path. |
| Used by | Incoming references. Selecting a column limits this list to that column and dependencies on the table or query shape. |
| Graph | Directed relationships from each using definition to its dependency. |
| Impact | An advisory assessment of rename, drop, type, and nullability changes. |
Dependency Graph
Select a node and expand it to follow its relationships. Drag to pan, use + and − to zoom, or reset around the selected node. Cycles are retained.
The graph displays at most 50 nodes and shows both the display limit and the connected object count. The relationship lists remain available beyond that visual limit.
Column Impact
Choose the column and the kind of change: Rename, Drop, Type, or Nullability. The assessment separates four kinds of findings:
- Confirmed usage: resolved references to the selected column.
- Indirect effects: downstream definitions affected through other objects and column lineage.
- Engine restrictions: rules that may prevent the requested schema operation.
- References needing review: unresolved or dynamic references and compatibility checks.
- Model membership: saved diagrams containing the affected table or column, including downstream definitions where relevant.
- Proposed changes: saved model edits that reference the affected object but have not been applied.
- Archive relationships: links described by registered archive metadata, without treating them as local database constraints.
Assess column impact is also available in the table explorer context menu, column actions and rename/drop screens, and Data Modeler's persisted-column inspector. Pending model changes are assessed against the saved column identity.
Engine restrictions are reported separately from reference findings. For example, rename, drop, or type operations may be blocked by a dependent view even when that view does not select the target column. Nullability changes do not use that view guard. Keys, foreign keys, indexes, triggers, validation rules, primary-key and identity storage, defaults, and checks follow the relevant operation's restrictions or compatibility checks.
Definition Coverage
The catalog captures saved definitions in the selected database or route:
- Tables, columns, defaults, keys, foreign keys, checks, validation rules, and indexes.
- Views, triggers, procedures (including disabled procedures), and saved queries.
- C# modules, persisted forms and reports, and current pipeline revisions.
- Saved Data Modeler diagrams, including diagram names, groups, member tables and columns, relationships, and persisted proposed changes.
- Registered external tables and archive relationships, inspected through their schema metadata.
Query Designer's internal layout records and historical pipeline revisions are excluded. Chunked reports, diagrams, and large source definitions are reassembled before searching.
Data models and proposed changes
Search a diagram name, table, column, or relationship name, then use the Data model or Proposed change object-type filter. Choose Open data model to open the saved diagram in the selected route. An existing open model retains its pending edits.
For a table or column, open Used by and choose Model membership to find diagrams containing it. Uses, Used by, the graph, and column-impact findings distinguish database usage, model membership, proposed changes, and archive relationships. The graph provides a relationship filter and a visible legend, with at most 50 objects and 200 relationships displayed at once.
Diagram membership describes documentation and maintenance impact; it does not enforce a schema constraint. Proposed changes are analyzed as saved design intent and never executed. Only changes persisted with a saved diagram are included. Existing schema identities are used to connect staged renames back to the current database when available.
Data Modeler's Known dependencies inspector uses the same analysis as Search, including SQL objects, forms, reports, modules, pipelines, and saved diagrams. Its Search links preserve the current route and object. Incomplete coverage is shown alongside the findings.
External archive metadata
Search inspects metadata from archives registered in the active database or route and identifies the archive path and source table. Archive aliases and relationships remain separate from same-named local tables. Missing or malformed archive metadata produces coverage diagnostics.
Only archive headers, schema, and metadata are inspected. Search does not scan stored rows or index pages, and this inspection does not verify the integrity of their payloads. Archive relationships are advisory metadata, not locally enforced database foreign keys.
Dependency Analysis
SQL references and column lineage
SQL analysis uses CSharpDB's parser. It handles aliases, joins, correlated and scalar subqueries, EXISTS and IN subqueries, CTE output aliases, compound queries, predicates, expressions, aggregates and windows, wildcard projections, read/write targets, positional inserts, and OLD/NEW trigger references.
Column lineage follows view and saved-query output names. Predicate changes affect a query's rows; rename and drop can invalidate the whole referencing definition. Type and nullability effects follow output lineage.
Forms, reports, and pipelines
- Forms: explicit bindings, child-table keys, lookup and display fields, SQL and procedure actions, and module bindings.
- Reports: sources, bound fields, expressions, grouping, and sorting fields.
- Pipelines: sources, transformations, destinations, and watermark fields. External connections and files are identified without opening them.
C# modules
Static inspection uses Roslyn syntax and semantic models to resolve supported constant API arguments and form field access. It flags dynamic, unbound, host, reflection, and indirect calls for review. Inspection never compiles an executable assembly, invokes a module, or grants module trust.
Coverage Diagnostics
Unrecognized SQL syntax, ambiguous fields, missing objects, malformed definitions, cycles that prevent column resolution, runtime-computed references, and unavailable catalog sections produce coverage diagnostics. Text search remains available for captured definitions.
Review these diagnostics alongside dependency findings. A lack of findings does not establish that arbitrary C# helpers or external systems have no dependencies.
Refresh and Cancellation
Catalog loading, dependency analysis, and text search run in the background so Studio can keep responding to navigation and cancellation while definitions are inspected.
Studio refreshes after local definition changes. Use manual refresh for changes made elsewhere. In-flight work can be cancelled; failed or cancelled refreshes retain clearly marked stale results for the same scope.
Changing the database or route cancels in-flight work and clears the previous results. Analysis caches SQL by source plus the complete relation/schema fingerprint and module inspection by source hash. The graph is rebuilt against each catalog.
Read-only Transport Contract
ICSharpDbDefinitionCatalogReader is an optional capability on embedded, HTTP, and gRPC clients. It is forwarded through CSharpDbClient, the Studio database holder, and route-bound clients. Older servers produce a recoverable unsupported-capability message.
ReadDefinitionCatalogAsync(continuationToken, pageSize, cancellationToken) returns a DefinitionCatalogPage. Page sizes are 1–64 records; a large definition uses consecutive source fragments of at most 8,192 UTF-16 code units.
Consumers follow continuation tokens until null, validate catalog versions, fragment metadata, and source SHA-256 hashes, then reassemble by definition ID and part index. DefinitionCatalogService.ReadAsync implements this consumer contract.
Paging snapshots
The first page captures definitions; later pages use the same immutable snapshot. Each embedded client keeps at most four paged snapshots, expiring after two minutes without a page read. Tokens are scoped to that client, database, and route, and expire on server restart. Expiration is recoverable by refreshing.
Manual refresh starts a fresh snapshot. This avoids rescanning the catalog for each page and mixing definitions captured at different times.
Remote access
- REST:
GET /api/catalog/definitions?pageSize=64&continuationToken=... - gRPC:
ReadDefinitionCatalog, with a JSON catalog-page payload injson_utf8.
Inspection reads existing schema and known metadata rows through a read-only reader. It does not initialize feature metadata tables, execute saved SQL, or invoke callbacks.
Verification and Performance
Focused tests cover matching, highlights and locations, SQL resolution and lineage, native bindings, malformed definitions, fragment integrity, cancellation, refresh, route and token isolation, actual engine restrictions, and non-invocation of stored SQL, modules, and callbacks. Model tests verify membership, proposed changes, stable identity resolution, relationship labels, navigation, and metadata-only archive reads. Embedded, REST, and gRPC contract tests compare every definition fragment, including Unicode source, chunked reports, saved models, external metadata, and current pipelines.
A local Debug run on September 9, 2026 measured 10,001 synthetic definitions with 30,000 reference edges:
| Operation | Observed time |
|---|---|
| Initial dependency analysis | 579 ms |
| Text search | 14 ms |
| Analysis on refresh using the cache | 71 ms |
| Read all pages of 10,001 persisted definitions | 182 ms |
These are local observations, not performance guarantees. UI rendering is bounded independently: 50 search results per page, 12,000 source characters per page, and expandable batches of relationship and diagnostic findings.
Scope
This feature analyzes saved definitions in the active database or selected route. Boolean, regex, fuzzy and semantic search, persistent indexes, automatic refactoring, and external repository scanning remain outside its scope.
FileSearcher was used for research only. The feature includes no FileSearcher code or dependencies.
Related guides: Studio / Admin UI, SQL Reference, Reports, and ETL Pipelines.