kodiakhq · Oct 8, 2026 · Sep 14, 2026 · Sep 14, 2026 · Sep 14, 2026 · Oct 7, 2026
@@ -0,0 +1,13 @@
+---
+'@hyperdx/app': patch
+---
+
+feat: choose how property keys are ordered in the row side panel
+
+The JSON viewer sorts keys alphabetically, which is the right default for wide
+ClickHouse `Map(...)` columns like `ProfileEvents` but hides the stored column
+order. The properties view options menu now offers "Sort keys A–Z", "Sort keys
+Z–A", and "Original order"; the choice persists with the viewer's other options.
+Array elements keep their index order in every mode. In "Original order",
+integer-like keys (e.g. HTTP status codes) still list first in ascending order,
+since parsed JavaScript objects order keys that way.
@@ -20,16 +20,21 @@ import {
   IconCheck,
   IconCopy,
   IconFilter,
+  IconList,
   IconMinus,
   IconPlus,
   IconSearch,
   IconSettings,
+  IconSortAscendingLetters,
+  IconSortDescendingLetters,
   IconTextWrap,
 } from '@tabler/icons-react';
 
 import HyperJson, {
+  DEFAULT_KEY_ORDER,
   FormatLeafValue,
   GetLineActions,
+  KeyOrder,
   LineAction,
 } from '@/components/HyperJson';
 import { useMaterializedAliasColumnsOption } from '@/hooks/useMaterializedAliasColumnsOption';
@@ -133,6 +138,9 @@ type ViewerOptions = {
   whiteSpace?: 'pre' | 'pre-wrap';
   tabulate: boolean;
   filterBlanks: boolean;
+  // Absent for options stored before sorting was configurable; falls back to
+  // the alphabetical default.
+  keyOrder?: KeyOrder;
 };
 
 const VIEWER_OPTIONS_KEY = 'hdx_json_viewer_options';
@@ -142,8 +150,31 @@ const DEFAULT_VIEWER_OPTIONS: ViewerOptions = {
   whiteSpace: 'pre-wrap',
   tabulate: true,
   filterBlanks: false,
+  keyOrder: DEFAULT_KEY_ORDER,
 };
 
+const KEY_ORDER_OPTIONS: {
+  value: KeyOrder;
+  label: string;
+  icon: React.ReactNode;
+}[] = [
+  {
+    value: 'asc',
+    label: 'Sort keys A–Z',
+    icon: <IconSortAscendingLetters size={14} />,
+  },
+  {
+    value: 'desc',
+    label: 'Sort keys Z–A',
+    icon: <IconSortDescendingLetters size={14} />,
+  },
+  {
+    value: 'original',
+    label: 'Original order',
+    icon: <IconList size={14} />,
+  },
+];
+
 /**
  * Migrates old `lineWrap` boolean to `whiteSpace` enum.
  *
@@ -239,6 +270,7 @@ function HyperJsonMenu({
   const [showMaterializedAliasColumns, setShowMaterializedAliasColumns] =
     useMaterializedAliasColumnsOption();
   const effectiveWhiteSpace = jsonOptions.whiteSpace ?? 'pre-wrap';
+  const effectiveKeyOrder = jsonOptions.keyOrder ?? DEFAULT_KEY_ORDER;
 
   return (
     <Group>
@@ -285,7 +317,7 @@ function HyperJsonMenu({
       </UnstyledButton>
       <Menu width={240} withinPortal={false}>
         <Menu.Target>
-          <UnstyledButton>
+          <UnstyledButton data-testid="json-viewer-options-menu">
             <IconSettings size={14} />
           </UnstyledButton>
         </Menu.Target>
@@ -361,6 +393,29 @@ function HyperJsonMenu({
               Show materialized and alias columns
             </Menu.Item>
           )}
+          <Menu.Divider />
+          <Menu.Label lh={1} py={6}>
+            Property order
+          </Menu.Label>
+          {KEY_ORDER_OPTIONS.map(({ value, label, icon }) => (
+            <Menu.Item
+              key={value}
+              data-testid={`json-viewer-key-order-${value}`}
+              lh="1"
+              py={8}
+              leftSection={icon}
+              rightSection={
+                effectiveKeyOrder === value ? (
+                  <IconCheck size={14} className="ps-2" />
+                ) : null
+              }
+              onClick={() =>
+                setJsonOptions({ ...jsonOptions, keyOrder: value })
+              }
+            >
+              {label}
+            </Menu.Item>
+          ))}
         </Menu.Dropdown>
       </Menu>
     </Group>

@@ -40,15 +40,30 @@ export type FormatLeafValue = (arg0: {
   value: unknown;
 }) => React.ReactNode | undefined;
 
+/**
+ * How object keys are ordered at every level of the tree.
+ *
+ * `original` keeps the object's own key order — for ClickHouse `Map(...)`
+ * columns, physical storage order — except that integer-like keys (`"200"`,
+ * `Map(UInt64, …)` keys) always come first in ascending numeric order. JS
+ * objects order keys that way, so the true order is already gone once the
+ * query result is parsed.
+ */
+export type KeyOrder = 'asc' | 'desc' | 'original';
+
+export const DEFAULT_KEY_ORDER: KeyOrder = 'asc';
+
 // Store common state in an atom so that it can be shared between components
 // to avoid prop drilling
 type HyperJsonAtom = {
   normallyExpanded: boolean;
+  keyOrder: KeyOrder;
   getLineActions?: GetLineActions;
   formatLeafValue?: FormatLeafValue;
 };
 const hyperJsonAtom = atom<HyperJsonAtom>({
   normallyExpanded: false,
+  keyOrder: DEFAULT_KEY_ORDER,
 });
 
 const ValueRenderer = React.memo(
@@ -273,6 +288,7 @@ const Line = React.memo(
         <div
           ref={ref}
           data-testid="json-viewer-line"
+          data-depth={nestedLevel}
           onClick={handleToggle}
           className={cx(styles.line, {
             [styles.nestedLine]: nestedLevel > 0,
@@ -358,6 +374,8 @@ function TreeNode({
 
   const originalLength = React.useMemo(() => Object.keys(data).length, [data]);
 
+  const { keyOrder } = useAtomValue(hyperJsonAtom);
+
   // ClickHouse hands back `Map(...)` keys in physical storage order, which reads
   // as random for wide maps like `ProfileEvents`. Sorting here (rather than
   // upstream) covers every nesting level for free, since TreeNode recurses, and
@@ -366,13 +384,15 @@ function TreeNode({
   const entries = React.useMemo(() => {
     const raw = Object.entries(data);
     // Arrays are index-keyed — reordering them would change the data.
-    if (isArray(data)) {
+    if (isArray(data) || keyOrder === 'original') {
       return raw;
     }
-    return raw.sort(([a], [b]) =>
-      a.localeCompare(b, undefined, { numeric: true }),
+    const direction = keyOrder === 'desc' ? -1 : 1;
+    return raw.sort(
+      ([a], [b]) =>
+        direction * a.localeCompare(b, undefined, { numeric: true }),
     );
-  }, [data]);
+  }, [data, keyOrder]);
 
   const visibleLines = React.useMemo(() => {
     return isExpanded ? entries : entries.slice(0, MAX_TREE_NODE_ITEMS);
@@ -430,6 +450,7 @@ type HyperJsonProps = {
   normallyExpanded?: boolean;
   tabulate?: boolean;
   whiteSpace?: 'pre' | 'pre-wrap';
+  keyOrder?: KeyOrder;
   getLineActions?: GetLineActions;
   formatLeafValue?: FormatLeafValue;
 };
@@ -439,16 +460,20 @@ const HyperJson = ({
   normallyExpanded = false,
   tabulate = false,
   whiteSpace = 'pre-wrap',
+  keyOrder = DEFAULT_KEY_ORDER,
   getLineActions,
   formatLeafValue,
 }: HyperJsonProps) => {
   const isEmpty = React.useMemo(() => Object.keys(data).length === 0, [data]);
 
+  const initialValues = React.useMemo(
+    () => ({ normallyExpanded, keyOrder, getLineActions, formatLeafValue }),
+    [normallyExpanded, keyOrder, getLineActions, formatLeafValue],
+  );
+
   return (
     <Provider>
-      <HydrateAtoms
-        initialValues={{ normallyExpanded, getLineActions, formatLeafValue }}
-      >
+      <HydrateAtoms initialValues={initialValues}>
         <div
           className={cx(styles.container, {
             [styles.withTabulate]: tabulate,

@@ -0,0 +1,111 @@
+import React from 'react';
+import { Provider } from 'jotai';
+import { MantineProvider } from '@mantine/core';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { DBRowJsonViewer } from '@/components/DBRowJsonViewer';
+import { RowSidePanelContext } from '@/components/DBRowSidePanel';
+
+jest.mock('next/router', () => ({
+  __esModule: true,
+  default: { push: jest.fn() },
+}));
+
+jest.mock('@/useFormatTime', () => ({
+  useFormatTime: () => (time: unknown) => String(time),
+  FormatTime: jest.fn(() => null),
+}));
+
+const VIEWER_OPTIONS_KEY = 'hdx_json_viewer_options';
+
+// Options written before the sort setting existed — no `keyOrder` key.
+const LEGACY_STORED_OPTIONS = {
+  normallyExpanded: true,
+  whiteSpace: 'pre-wrap',
+  tabulate: true,
+  filterBlanks: false,
+};
+
+const data = { zebra: 'z', alpha: 'a', Mango: 'm' };
+
+// env="test" mounts the menu dropdown without a transition to wait on. The
+// viewer options atom is module-scoped, so each render gets its own jotai store;
+// the atom then reads localStorage when it mounts in that store.
+const renderViewer = () =>
+  render(
+    <Provider>
+      <MantineProvider env="test">
+        <RowSidePanelContext value={{}}>
+          <DBRowJsonViewer data={data} />
+        </RowSidePanelContext>
+      </MantineProvider>
+    </Provider>,
+  );
+
+const renderedKeys = (container: HTMLElement) =>
+  Array.from(container.querySelectorAll('.keyContainer > .key')).map(el =>
+    el.textContent?.trim(),
+  );
+
+const openOptionsMenu = async () => {
+  await userEvent.click(screen.getByTestId('json-viewer-options-menu'));
+  await screen.findByRole('menu');
+};
+
+const selectKeyOrder = async (value: 'asc' | 'desc' | 'original') => {
+  await openOptionsMenu();
+  await userEvent.click(screen.getByTestId(`json-viewer-key-order-${value}`));
+};
+
+const storedKeyOrder = () =>
+  JSON.parse(localStorage.getItem(VIEWER_OPTIONS_KEY) ?? '{}').keyOrder;
+
+describe('DBRowJsonViewer key order', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('sorts alphabetically when stored options predate the setting', async () => {
+    localStorage.setItem(
+      VIEWER_OPTIONS_KEY,
+      JSON.stringify(LEGACY_STORED_OPTIONS),
+    );
+    const { container } = renderViewer();
+
+    expect(renderedKeys(container)).toEqual(['alpha', 'Mango', 'zebra']);
+
+    await openOptionsMenu();
+    expect(
+      screen.getByTestId('json-viewer-key-order-asc').querySelector('.ps-2'),
+    ).toBeInTheDocument();
+  });
+
+  it('restores a stored order on render', async () => {
+    localStorage.setItem(
+      VIEWER_OPTIONS_KEY,
+      JSON.stringify({ ...LEGACY_STORED_OPTIONS, keyOrder: 'original' }),
+    );
+    const { container } = renderViewer();
+
+    expect(renderedKeys(container)).toEqual(['zebra', 'alpha', 'Mango']);
+  });
+
+  it('switches between the stored order and reverse alphabetical', async () => {
+    const { container } = renderViewer();
+
+    expect(renderedKeys(container)).toEqual(['alpha', 'Mango', 'zebra']);
+
+    await selectKeyOrder('original');
+    expect(renderedKeys(container)).toEqual(['zebra', 'alpha', 'Mango']);
+    expect(storedKeyOrder()).toBe('original');
+
+    await selectKeyOrder('desc');
+    expect(renderedKeys(container)).toEqual(['zebra', 'Mango', 'alpha']);
+    expect(storedKeyOrder()).toBe('desc');
+
+    await selectKeyOrder('asc');
+    expect(renderedKeys(container)).toEqual(['alpha', 'Mango', 'zebra']);
+    expect(storedKeyOrder()).toBe('asc');
+  });
+});
@@ -32,6 +32,7 @@ describe('migrateViewerOptions', () => {
       whiteSpace: undefined,
       tabulate: true,
       filterBlanks: false,
+      keyOrder: 'asc',
     });
   });
 
@@ -48,6 +49,8 @@ describe('migrateViewerOptions', () => {
       whiteSpace: 'pre-wrap',
       tabulate: true,
       filterBlanks: false,
+      // Migration fills in the defaults for options added later.
+      keyOrder: 'asc',
     });
   });
 

@@ -76,6 +76,31 @@ describe('HyperJson key ordering', () => {
     ]);
   });
 
+  it('reverses the order with keyOrder="desc"', () => {
+    const { container } = renderWithMantine(
+      <HyperJson data={{ zebra: 1, alpha: 2, Mango: 3 }} keyOrder="desc" />,
+    );
+
+    expect(renderedKeys(container)).toEqual(['zebra', 'Mango', 'alpha']);
+  });
+
+  it('keeps the incoming order with keyOrder="original"', () => {
+    const { container } = renderWithMantine(
+      <HyperJson
+        data={{ ProfileEvents: { Seek: 59, FileOpen: 2, Query: 1 } }}
+        keyOrder="original"
+        normallyExpanded
+      />,
+    );
+
+    expect(renderedKeys(container)).toEqual([
+      'ProfileEvents',
+      'Seek',
+      'FileOpen',
+      'Query',
+    ]);
+  });
+
   it('orders numeric suffixes naturally rather than lexicographically', () => {
     const { container } = renderWithMantine(
       <HyperJson data={{ key10: 1, key2: 2, key1: 3 }} />,