Explore, sample and profile

FACE learns about a source in three steps. Each step reads more than the one before it, and each is bounded separately.

Explore

Explore asks the connector to describe what the source holds, without assuming anything about its data model. The response is:

• description (SourceDescription), which is never unset on a non-error return:
  • supported: whether this source has a catalogue that FACE can read.
  • reason: a human-readable explanation. Display it; do not match on it.
  • datasets[]: each DescribedDataset has a name, a kind (table, view, entity set, topic, media track, …), a qualifier (for example DATABASE.SCHEMA or catalog.schema) and columns[], plus row counts, relationships, tags and partition keys where the source states them. datasets[].sample is always unset here, because Explore does not sample.
  • aspects[]: which questions were asked (asked), whether the answer was readable (readable), the source call used (source), and a detail. Check this before concluding that something is absent.
• discovery_attempted: whether a connector’s discovery actually ran. It is false when the id did not resolve or the type has no connector. true together with supported=false is a normal, useful answer for a source with no catalogue.

Every *_stated flag in the description means the source itself said so. A column’s nullable is meaningful only when nullable_stated is true, and the same rule applies to units, row counts, sizes and last-altered times. FACE never fills these in from defaults.

Which values may leave a source during Explore

Explore reads metadata only. It does not read:

• row counts that would need a scan (COUNT(*))
• most-common-value lists or histograms, because those are literal customer values
• sample rows

A catalogue is permission-filtered. What comes back is what this credential can see, which may be smaller than what exists.

Explore support by connector

Sample

SampleConnectionDataset is the one ConfigService RPC that moves customer data. You name one dataset by qualifier and name, exactly as Explore reported them. The server re-quotes both parts for each engine. Every identifier part goes through an identifier allowlist first, and a name that the allowlist rejects is refused with the reason. It is never escaped or quoted around.

Bounds:

• row_limit must be in 0..1000. 0 means the connector’s default. A value outside that range is refused, not clamped.

• Each connector applies its own ceiling:

  Connector	Default rows	Ceiling	Cell size cap	Method
  Snowflake	10	100	512 bytes	FIXED_SIZE_RANDOM (SAMPLE (n ROWS))
  Databricks	25	1000 (above is refused)	4096 bytes	FIRST_ROWS (the first rows the engine produced)

• Any other type answers sampled: false with: this backend has not implemented bounded sampling for a “…” source. That statement is about FACE, not about your source.

Before sampling, the server explores the dataset to learn its governance (masked columns, row filters). The response sample then carries:

• columns and rows. Each SampleCell separates is_null from an empty value.
• method and method_detail: the statistical class and the source’s own clause.
• masked_columns, row_filter and governance_checked. governance_checked is false when the governance answer could not be obtained.
• caveats, which is never empty.

Show masked_columns, row_filter and governance_checked beside the rows. A masked column returns its masked value and still counts as a successful read.

Sampled rows are not the dataset. A null rate, a distinct count or an absent value computed over 25 rows says nothing about the table.

Profile

When FACE builds the estate map for analysis, it profiles each connection within fixed budgets:

• Which datasets. At most 12 datasets per connection are profiled, taken in catalogue order. The result reports datasets_profiled next to datasets_discovered.

• Sample reads. FACE reads the columns it names from the catalogue. It never uses SELECT * and adds no COUNT(*). The default is 25 rows, with ceilings of 100 rows, 64 columns and 512 bytes per value.

• Time. The deadline is 30 s by default and at most 2 minutes. The deadline bounds how long FACE waits, not the work the warehouse does.

• Statistics. An optional aggregate pass computes, per column:

  • non-null and null counts
  • null rate
  • distinct count
  • range (min/max)
  • mean and standard deviation

  Each figure carries a *Stated flag and a basis. A range can be withheld with a stated reason.

• Opting out. A connection listed in metadata_only_connection_ids is read for its catalogue only, and no data is read.

No sampled value is ever written to a log.