Eternet Portal Documentation

Query Builder

Workflow

  1. Select a managed or external datasource.
  2. Browse available schemas, tables, and columns.
  3. Choose fields and configure supported filters, sorting, grouping, or joins.
  4. Execute the query and inspect the normalized tabular result.
  5. Save reusable query or dataset definitions where supported.

Execution

The portal calls the Analytics API for metadata and query execution. The backend owns connector access, Arrow normalization, and DuckDB processing. The portal may add time-range filters when it can identify a time column; if none is identifiable, it cannot safely apply that range automatically.

External source setup

Datasource creation includes a connection test and server-side save workflow. A successful form submission alone does not prove every future query will succeed; verify connectivity, metadata, and a representative execution.

Designing a query that answers the question

The builder is intended to make source exploration and query configuration understandable as a sequence. Start by choosing a datasource whose ownership and refresh behavior are known. Browse schemas and tables to identify the authoritative record, then inspect columns for identifiers, event times, and values. Choose only the fields required for the question, because projection can reduce transferred data and make result interpretation easier. Apply filters using the correct value type and define a time range only after confirming which column represents event time. When the query combines sources, identify the join keys and their cardinality before executing; a one-to-many join can multiply rows and distort totals even when the SQL is valid.

Metadata browsing and query execution use the Analytics API rather than direct browser connections to databases. This keeps datasource credentials out of the browser and gives the service a place to enforce authentication, connector configuration, and query policy. The portal exposes source test and save flows for external datasource configuration, but a successful connection test only confirms connectivity for that test. Metadata discovery and a representative query are still needed to validate schema permissions, data access, and result shape.

Execution semantics and result review

At the backend, ADBC is preferred when a connector driver is available; a native adapter is used where no suitable driver exists. Connector outputs are normalized into Apache Arrow. DuckDB applies the final relational work, including cross-source joins and post-connector filtering, ordering, and aggregation. Filters, projections, time windows, and aggregations can be pushed down when a source connector supports them, but the user should not assume that every operation is pushed down. The engine abstraction is replaceable, and Trino is not part of the current implementation.

After execution, review both the returned columns and representative rows. Check that timestamps are parsed as intended, numeric values have the expected units, nulls are acceptable, and aggregation levels match the use case. The result normalizer accepts multiple response shapes and builds a consistent table, but it cannot infer business semantics or repair a wrong query. If the builder cannot identify a time column, an automatic date filter may not be applied; check the query payload and resulting timestamps.

Save, reuse, and share responsibly

A saved query captures a repeatable definition; a dataset is a reusable tabular input that can support downstream work such as forecasting. Saving should follow a successful execution and a clear owner/access decision. Forecast reuses Analytics source resolution, so a reference should be authorized for the caller and must not be treated as a public URL. For a customer demonstration, explain the source, columns, filters, join logic, and time window in plain language. Show a known result and state any limitations such as sampling, incomplete time coverage, or upstream availability. This is more credible than presenting a chart without being able to explain how its data was selected.