feat(app): add an option to show MATERIALIZED and ALIAS columns in the row details panel

.changeset/row-panel-materialized-alias-columns.md

@@ -0,0 +1,15 @@
+---
+'@hyperdx/app': patch
+---
+
+feat: add an option to show MATERIALIZED and ALIAS columns in the row details panel
+
+ClickHouse leaves MATERIALIZED and ALIAS columns out of `SELECT *`, so the row
+details panel never showed them. A new "Show materialized and alias columns"
+item in the properties view options menu, off by default, adds
+`asterisk_include_materialized_columns` and `asterisk_include_alias_columns` to
+the row query. It has no effect on a source with a Known Columns List, and a
+value that the source's query settings give for either setting wins. If the row
+fails to load while the option is on (for example, because the connection's user
+is `readonly = 1`, or an ALIAS column cannot be evaluated), the error state
+offers to turn the option off.

packages/app/src/components/DBRowDataPanel.tsx

@@ -10,6 +10,11 @@ import {
 import { Box } from '@mantine/core';
 
 import { useQueriedChartConfig } from '@/hooks/useChartConfig';
+import {
+  getKnownColumnsList,
+  getSelectAllColumnsQuerySettings,
+  useSelectAllColumnsQuerySettings,
+} from '@/hooks/useMaterializedAliasColumnsOption';
 import { WithClause } from '@/hooks/useRowWhere';
 import {
   getDisplayedTimestampValueExpression,
@@ -90,10 +95,7 @@ export function useRowData({
   // target tables declare different column sets. When the source declares a
   // "known columns" list (columns known to exist across all target tables) we
   // select that instead of `*` when fetching full row data.
-  const knownColumns =
-    isLogSource(source) || isTraceSource(source)
-      ? source.knownColumnsListExpression?.trim()
-      : undefined;
+  const knownColumns = getKnownColumnsList(source);
 
   const baseConfig = {
     source: source.id,
@@ -210,6 +212,8 @@ export function useRowData({
     ...(aliasWith && aliasWith.length > 0 ? { with: aliasWith } : {}),
   };
 
+  const additionalQuerySettings = useSelectAllColumnsQuerySettings(source);
+
   const baseQueryKey = ['row_side_panel', rowId, aliasWith, source];
   // Both halves of the filter are needed for `renderChartConfig` to emit one, so
   // a source with no usable timestamp expression can't be bounded at all.
@@ -225,6 +229,7 @@ export function useRowData({
     {
       queryKey: [...baseQueryKey, dateRange],
       enabled: rowId != null && hasWindow,
+      additionalQuerySettings,
     },
   );
 
@@ -245,6 +250,7 @@ export function useRowData({
   const fallbackResult = useQueriedChartConfig(baseConfig, {
     queryKey: [...baseQueryKey, undefined],
     enabled: rowId != null && isFallbackActive,
+    additionalQuerySettings,
   });
 
   const queryResult = isFallbackActive ? fallbackResult : boundedResult;
@@ -379,6 +385,9 @@ export function RowDataPanel({
           data={firstRow}
           jsonColumns={jsonColumns}
           mapColumns={mapColumns}
+          showMaterializedAliasColumnsOption={
+            getSelectAllColumnsQuerySettings(source) != null
+          }
         />
       </Box>
     </div>

packages/app/src/components/DBRowJsonViewer.test.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import { fireEvent, screen, within } from '@testing-library/react';
 
+import { useMaterializedAliasColumnsOption } from '@/hooks/useMaterializedAliasColumnsOption';
+
 import { buildJSONExtractQuery, DBRowJsonViewer } from './DBRowJsonViewer';
 import { RowSidePanelContext } from './DBRowSidePanel';
 
@@ -186,6 +188,46 @@ describe('DBRowJsonViewer', () => {
     expect(mockToggleColumn).toHaveBeenCalledWith("LogAttributes['field1']");
   });
 
+  it('turns the materialized and alias columns option on and off from the menu', async () => {
+    const OptionValue = () => (
+      <span data-testid="materialized-alias-option">
+        {String(useMaterializedAliasColumnsOption()[0])}
+      </span>
+    );
+    const { container } = renderWithMantine(
+      <RowSidePanelContext value={defaultContext}>
+        <DBRowJsonViewer data={logData} showMaterializedAliasColumnsOption />
+        <OptionValue />
+      </RowSidePanelContext>,
+    );
+    const option = screen.getByTestId('materialized-alias-option');
+    const toggle = async () => {
+      fireEvent.click(container.querySelector('[aria-haspopup="menu"]')!);
+      fireEvent.click(
+        await screen.findByTestId('json-viewer-materialized-alias-toggle'),
+      );
+    };
+
+    expect(option).toHaveTextContent('false');
+    await toggle();
+    expect(option).toHaveTextContent('true');
+    expect(
+      localStorage.getItem('hdx-row-show-materialized-alias-columns'),
+    ).toBe('true');
+    await toggle();
+    expect(option).toHaveTextContent('false');
+  });
+
+  it('hides the materialized and alias columns option unless asked to show it', async () => {
+    const { container } = renderComponent(logData);
+    fireEvent.click(container.querySelector('[aria-haspopup="menu"]')!);
+
+    expect(await screen.findByText('Hide blank values')).toBeInTheDocument();
+    expect(
+      screen.queryByTestId('json-viewer-materialized-alias-toggle'),
+    ).not.toBeInTheDocument();
+  });
+
   describe('timestamp fields', () => {
     it('displays Timestamp using the same formatter as the results table', () => {
       renderComponent({

packages/app/src/components/DBRowJsonViewer.tsx

@@ -32,6 +32,7 @@ import HyperJson, {
   GetLineActions,
   LineAction,
 } from '@/components/HyperJson';
+import { useMaterializedAliasColumnsOption } from '@/hooks/useMaterializedAliasColumnsOption';
 import { useFormatTime } from '@/useFormatTime';
 import { isColumnInSelect, mergePath } from '@/utils';
 import {
@@ -227,8 +228,16 @@ const viewerOptionsAtom = atomWithStorage<ViewerOptions>(
   viewerOptionsStorage,
 );
 
-function HyperJsonMenu({ rowData }: { rowData: any }) {
+function HyperJsonMenu({
+  rowData,
+  showMaterializedAliasColumnsOption,
+}: {
+  rowData: any;
+  showMaterializedAliasColumnsOption: boolean;
+}) {
   const [jsonOptions, setJsonOptions] = useAtom(viewerOptionsAtom);
+  const [showMaterializedAliasColumns, setShowMaterializedAliasColumns] =
+    useMaterializedAliasColumnsOption();
   const effectiveWhiteSpace = jsonOptions.whiteSpace ?? 'pre-wrap';
 
   return (
@@ -335,6 +344,23 @@ function HyperJsonMenu({ rowData }: { rowData: any }) {
           >
             Hide blank values
           </Menu.Item>
+          {showMaterializedAliasColumnsOption && (
+            <Menu.Item
+              lh="1"
+              py={8}
+              data-testid="json-viewer-materialized-alias-toggle"
+              rightSection={
+                showMaterializedAliasColumns ? (
+                  <IconCheck size={14} className="ps-2" />
+                ) : null
+              }
+              onClick={() =>
+                setShowMaterializedAliasColumns(!showMaterializedAliasColumns)
+              }
+            >
+              Show materialized and alias columns
+            </Menu.Item>
+          )}
         </Menu.Dropdown>
       </Menu>
     </Group>
@@ -345,13 +371,17 @@ export function DBRowJsonViewer({
   data,
   jsonColumns,
   mapColumns,
+  showMaterializedAliasColumnsOption = false,
 }: {
   data: any;
   jsonColumns?: string[];
   // Map column names from the result-set metadata. Threaded into
   // `mergePath` so numeric-looking sub-keys on a Map render as
   // `Map['key']` instead of the array `Map[N+1]`. HDX-4369.
   mapColumns?: string[];
+  // Only a viewer of the whole row from `useRowData` is affected by the option,
+  // and only when the source's row query would change.
+  showMaterializedAliasColumnsOption?: boolean;
 }) {
   const formatTime = useFormatTime();
   const {
@@ -699,7 +729,12 @@ export function DBRowJsonViewer({
             </Button>
           )}
           <div className="flex-grow-1" />
-          <HyperJsonMenu rowData={rowData} />
+          <HyperJsonMenu
+            rowData={rowData}
+            showMaterializedAliasColumnsOption={
+              showMaterializedAliasColumnsOption
+            }
+          />
         </Group>
       </Box>
       <Paper bg="transparent" mt="sm">

packages/app/src/components/DBRowSidePanelErrorState.tsx

@@ -14,6 +14,10 @@ import { useDisclosure } from '@mantine/hooks';
 import { IconAlertTriangle } from '@tabler/icons-react';
 
 import { IS_LOCAL_MODE } from '@/config';
+import {
+  useMaterializedAliasColumnsOption,
+  useSelectAllColumnsQuerySettings,
+} from '@/hooks/useMaterializedAliasColumnsOption';
 import { useTableMetadata } from '@/hooks/useMetadata';
 import { useBrandDisplayName } from '@/theme/ThemeProvider';
 
@@ -82,6 +86,30 @@ function KnownColumnsListHint({
   );
 }
 
+// The option lives in the Column Values menu, which a failed row does not show.
+function MaterializedAliasColumnsHint({ onHide }: { onHide: () => void }) {
+  return (
+    <Alert
+      variant="warning"
+      icon={<IconAlertTriangle size={16} />}
+      title="Materialized and alias columns are on"
+      data-testid="materialized-alias-columns-hint"
+    >
+      <Stack gap="xs" align="start">
+        <Text size="sm">
+          The row query includes MATERIALIZED and ALIAS columns. The whole row
+          fails to load if the connection&apos;s user cannot change query
+          settings (for example, a readonly user) or if one of these columns
+          cannot be evaluated.
+        </Text>
+        <Button size="xs" variant="subtle" onClick={onHide}>
+          Hide materialized and alias columns
+        </Button>
+      </Stack>
+    </Alert>
+  );
+}
+
 export function DBRowSidePanelErrorState({
   error,
   source,
@@ -94,6 +122,9 @@ export function DBRowSidePanelErrorState({
 
   const showHint =
     isMissingColumnError(error) && !!tableMetadata?.isPointerTable;
+  const selectAllColumnsSettings = useSelectAllColumnsQuerySettings(source);
+  const [, setShowMaterializedAliasColumns] =
+    useMaterializedAliasColumnsOption();
 
   return (
     <Stack gap="sm" data-testid="row-error-state">
@@ -103,6 +134,12 @@ export function DBRowSidePanelErrorState({
         <KnownColumnsListHint onEditClick={editModal.open} source={source} />
       )}
 
+      {selectAllColumnsSettings != null && (
+        <MaterializedAliasColumnsHint
+          onHide={() => setShowMaterializedAliasColumns(false)}
+        />
+      )}
+
       <Stack align="start">
         <Text size="sm" mt={10}>
           Error Message: