:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { useActions, useValues } from 'kea'
import { Form } from 'kea-forms'
import { useRef } from 'react'
import {
LemonButton,
LemonInput,
LemonInputSelect,
LemonModal,
LemonSegmentedButton,
LemonSelect,
LemonTag,
LemonTextArea,
Link,
Spinner,
} from '@posthog/lemon-ui'
import { LemonBanner } from 'lib/lemon-ui/LemonBanner'
import { LemonField } from 'lib/lemon-ui/LemonField'
import { LemonTable, LemonTableColumns } from 'lib/lemon-ui/LemonTable'
import type { CodeEditorProps } from 'lib/monaco/CodeEditor'
import { CodeEditorResizeable } from 'lib/monaco/CodeEditorResizable'
import { escapePropertyAsHogQLIdentifier } from 'lib/utils/hogql'
import { urls } from 'scenes/urls'
import type { DataQualitySubjectRef } from './checksApi'
import { checkTypeLabel, subjectTypeLabel } from './checksConstants'
import { dataQualityCheckEditorLogic } from './dataQualityCheckEditorLogic'
import { CheckTypeEnumApi, DataQualityCheckSeverityEnumApi } from './generated/api.schemas'
import { formatPreviewCell } from './previewCell'
type CodeEditorInstance = Parameters<NonNullable<CodeEditorProps['onMount']>>[0]
export function CheckEditorModal(): JSX.Element {
const {
isOpen,
editingCheck,
checkForm,
checkTypes,
checkTypesError,
checkTypesLoading,
requiresColumn,
availableColumns,
openedWithoutSubject,
selectableSubjects,
checkSubjectsLoading,
checkSubjectsError,
subject,
isCheckFormSubmitting,
serverError,
} = useValues(dataQualityCheckEditorLogic)
// Which fields the form has depends on the check-type catalog, so showing the form before it
// arrives means fields appearing under the user's cursor a moment later.
const formShapeLoading = checkTypesLoading && !checkTypes.length
const awaitingSubject = openedWithoutSubject && !subject
const checkTypesFailedEmpty = checkTypesError && !checkTypesLoading && !checkTypes.length
const catalogFailed = !!checkSubjectsError && !checkSubjectsLoading
const { loadCheckTypes, loadCheckSubjects, requestClose, setCheckFormValues, setSubject, submitCheckForm } =
useActions(dataQualityCheckEditorLogic)
return (
<LemonModal
isOpen={isOpen}
onClose={requestClose}
title={editingCheck ? 'Edit check' : 'New check'}
width={640}
footer={
<div className="flex flex-col items-end gap-2 w-full">
{serverError && <span className="text-danger text-sm">{serverError}</span>}
<div className="flex gap-2">
<LemonButton type="secondary" onClick={requestClose}>
Cancel
</LemonButton>
<LemonButton
type="primary"
onClick={submitCheckForm}
loading={isCheckFormSubmitting}
disabledReason={
awaitingSubject
? 'Pick a table, view, or metric first'
: isCheckFormSubmitting
? 'Saving'
: formShapeLoading
? 'Loading the check types'
: checkTypesFailedEmpty
? 'Load the check types to continue'
: catalogFailed && !openedWithoutSubject
? 'Load the columns to continue'
: undefined
}
data-attr="data-quality-check-save"
>
Save check
</LemonButton>
</div>
</div>
}
>
{formShapeLoading && (
<div className="flex items-center gap-2 py-8 justify-center text-secondary">
<Spinner className="text-xl" />
<span>Loading check types...</span>
</div>
)}
{openedWithoutSubject && (
<div className="flex flex-col gap-2 mb-3">
<LemonField.Pure label="Table, view, or metric">
<LemonInputSelect
mode="single"
value={subject ? [`${subject.subjectType}:${subject.subjectId}`] : []}
options={selectableSubjects.map((candidate) => ({
key: `${candidate.type}:${candidate.id}`,
label: candidate.name,
labelComponent: (
<div className="flex items-center justify-between gap-2 w-full">
<span>{candidate.name}</span>
<LemonTag type="muted" size="small">
{subjectTypeLabel(candidate.type)}
</LemonTag>
</div>
),
}))}
onChange={(selectedKeys) => {
const selected = selectableSubjects.find(
(candidate) => `${candidate.type}:${candidate.id}` === selectedKeys[0]
)
if (!selected) {
return
}
const selectedSubject: DataQualitySubjectRef = {
subjectId: selected.id,
subjectType: selected.type,
}
setSubject(selectedSubject)
}}
loading={checkSubjectsLoading}
placeholder="Search tables, views, and metrics"
data-attr="data-quality-check-subject"
/>
</LemonField.Pure>
{catalogFailed ? (
<div className="flex items-center gap-2 text-secondary text-sm">
<span>Couldn't load what you can check.</span>
<LemonButton size="small" type="secondary" onClick={loadCheckSubjects}>
Retry
</LemonButton>
</div>
) : null}
{!checkSubjectsLoading && selectableSubjects.length === 0 ? (
<p className="mb-0 text-secondary text-sm">
<Link to={urls.database()}>Browse tables and views</Link> or{' '}
<Link to={urls.metrics()}>create a HogQL metric</Link> first.
</p>
) : null}
</div>
)}
{catalogFailed && !openedWithoutSubject && (
<div className="flex items-center gap-2 mb-3 text-secondary text-sm">
<span>Couldn't load the columns for this subject.</span>
<LemonButton size="small" type="secondary" onClick={loadCheckSubjects}>
Retry
</LemonButton>
</div>
)}
{checkTypesFailedEmpty && (
<div className="flex items-center gap-2 py-8 justify-center text-secondary">
<span>Couldn't load check types.</span>
<LemonButton size="small" type="secondary" onClick={loadCheckTypes}>
Retry
</LemonButton>
</div>
)}
<Form
logic={dataQualityCheckEditorLogic}
formKey="checkForm"
className={
formShapeLoading || awaitingSubject || checkTypesFailedEmpty ? 'hidden' : 'flex flex-col gap-3'
}
>
<LemonField name="checkType" label="Check type">
<LemonSelect
options={checkTypes.map((checkType) => ({
value: checkType.check_type as CheckTypeEnumApi,
label: checkTypeLabel(checkType.check_type),
labelInMenu: (
<div className="flex flex-col">
<span>{checkTypeLabel(checkType.check_type)}</span>
<span className="text-secondary text-xs">{checkType.description}</span>
</div>
),
}))}
onChange={(checkType) =>
// The config fields belong to the type that was selected, so they can't carry over.
setCheckFormValues({
checkType,
columnName: '',
acceptedValues: [],
toSubjectUuid: '',
toColumn: '',
rowCountMin: null,
rowCountMax: null,
maxAgeMinutes: null,
customSql: '',
})
}
/>
</LemonField>
{requiresColumn && (
<LemonField name="columnName" label="Column">
<LemonSelect
loading={checkSubjectsLoading && !availableColumns.length}
options={availableColumns.map((column) => ({ value: column, label: column }))}
/>
</LemonField>
)}
<CheckConfigFields checkType={checkForm.checkType} />
<LookbackField />
<LemonField
name="name"
label="Name"
showOptional
help="Lets you refer to this check by name in SQL and the API instead of by its id. Letters, numbers and underscores, starting with a letter."
>
<LemonInput placeholder="orders_customer_id_not_null" />
</LemonField>
<LemonField
name="description"
label="Description"
showOptional
help="Why this check exists and what a failure means. Shown to whoever finds the check failing."
>
<LemonTextArea placeholder="Every order has to belong to a customer" minRows={2} />
</LemonField>
<LemonField name="severity" label="Severity">
<LemonSegmentedButton
options={[
{ value: DataQualityCheckSeverityEnumApi.Error, label: 'Error' },
{ value: DataQualityCheckSeverityEnumApi.Warn, label: 'Warning' },
]}
/>
</LemonField>
<LemonField name="tags" label="Tags" showOptional>
<LemonInputSelect mode="multiple" allowCustomValues options={[]} placeholder="Add a tag" />
</LemonField>
</Form>
</LemonModal>
)
}
function CheckConfigFields({ checkType }: { checkType: CheckTypeEnumApi }): JSX.Element | null {
switch (checkType) {
case CheckTypeEnumApi.AcceptedValues:
return (
<LemonField name="acceptedValues" label="Allowed values">
<LemonInputSelect mode="multiple" allowCustomValues options={[]} placeholder="Add a value" />
</LemonField>
)
case CheckTypeEnumApi.Relationships:
return <RelationshipFields />
case CheckTypeEnumApi.RowCount:
return (
<div className="flex gap-3">
<LemonField name="rowCountMin" label="Minimum rows" showOptional className="flex-1">
<LemonInput type="number" min={0} />
</LemonField>
<LemonField name="rowCountMax" label="Maximum rows" showOptional className="flex-1">
<LemonInput type="number" min={0} />
</LemonField>
</div>
)
case CheckTypeEnumApi.Freshness:
return (
<LemonField
name="maxAgeMinutes"
label="Maximum age in minutes"
help="The check fails when the newest value in the column is older than this."
>
<LemonInput type="number" min={1} />
</LemonField>
)
case CheckTypeEnumApi.CustomSql:
return <CustomSqlField />
default:
return null
}
}
function CustomSqlField(): JSX.Element {
const {
customSqlEditorError,
customSqlPreview,
customSqlPreviewError,
customSqlPreviewLoading,
customSqlPreviewStale,
customSqlPreviewVerdict,
customSqlQueryKey,
customSqlSourceQuery,
isMetricSubject,
availableOutputSchema,
metricOutputSchemaError,
metricOutputSchemaLoading,
} = useValues(dataQualityCheckEditorLogic)
const { loadMetricOutputSchema, runCustomSqlPreview, setCustomSqlEditorError, setCustomSqlValidationLoading } =
useActions(dataQualityCheckEditorLogic)
const editorRef = useRef<CodeEditorInstance | null>(null)
const insertOutputColumn = (columnName: string): void => {
const editor = editorRef.current
const selection = editor?.getSelection()
if (!editor || !selection) {
return
}
editor.executeEdits('data-quality-output-schema', [
{
range: selection,
text: escapePropertyAsHogQLIdentifier(columnName),
forceMoveMarkers: true,
},
])
editor.focus()
}
const previewRows = customSqlPreview?.rows ?? []
// Key and index by position, not by column name: HogQL can return two columns with the same name
// (e.g. `SELECT id, id`), which would collide on an object key and on the React header key.
const previewColumns: LemonTableColumns<unknown[]> =
customSqlPreview?.columns.map((column, index) => ({
title: column,
key: String(index),
dataIndex: index,
// Never hand a raw object to LemonTable: it would spread the value's `props` onto the cell.
render: (value: unknown) => formatPreviewCell(value),
})) ?? []
return (
<LemonField
name="customSql"
label="Query"
help={
isMetricSubject
? 'Query the saved metric output through {metric} exactly once. Return one row per failure; no rows means the check passes. Save the check, then run it to see the result.'
: 'Return one row per failure. The check passes when the query returns nothing.'
}
>
{({ value, onChange }) => (
<div className="flex flex-col gap-2">
<CodeEditorResizeable
language="hogQL"
value={value ?? ''}
onChange={(query) => onChange(query ?? '')}
queryKey={customSqlQueryKey}
sourceQuery={customSqlSourceQuery}
metadataQuery={isMetricSubject ? '' : undefined}
onError={isMetricSubject ? undefined : setCustomSqlEditorError}
onMetadataLoading={isMetricSubject ? undefined : setCustomSqlValidationLoading}
onPressCmdEnter={isMetricSubject ? undefined : () => runCustomSqlPreview(undefined)}
onMount={(editor) => {
editorRef.current = editor
}}
autoFocus
minHeight="8rem"
maxHeight="40vh"
/>
<div className="rounded border bg-surface-primary overflow-hidden">
<div className="flex items-center justify-between gap-2 px-3 py-2 border-b">
<div>
<div className="font-semibold text-sm">Available columns</div>
<div className="text-secondary text-xs">
Select a column to insert it into the query.
</div>
</div>
{metricOutputSchemaLoading && <Spinner />}
</div>
{metricOutputSchemaError ? (
<div className="flex items-center justify-between gap-2 px-3 py-2 text-sm">
<span className="text-secondary">
Couldn't load the metric output schema. You can still write the query manually.
</span>
<LemonButton
size="small"
type="secondary"
onClick={() => loadMetricOutputSchema(undefined)}
>
Retry
</LemonButton>
</div>
) : !metricOutputSchemaLoading && availableOutputSchema.length === 0 ? (
<p className="mb-0 px-3 py-2 text-secondary text-sm">
No output columns were found. You can still write the query manually.
</p>
) : (
<div className="flex flex-col max-h-40 overflow-y-auto p-1">
{availableOutputSchema.map((column) => (
<LemonButton
key={column.name}
type="tertiary"
size="small"
fullWidth
onClick={() => insertOutputColumn(column.name)}
data-attr="data-quality-check-output-column"
>
<span className="flex items-center justify-between gap-2 w-full">
<code>{column.name}</code>
{column.type && (
<LemonTag type="muted" size="small">
{column.type}
</LemonTag>
)}
</span>
</LemonButton>
))}
</div>
)}
</div>
{!isMetricSubject && (
<div className="flex flex-col items-end gap-1">
<LemonButton
type="secondary"
size="small"
loading={customSqlPreviewLoading}
disabledReason={
!value?.trim()
? 'Write a query before testing it.'
: (customSqlEditorError ?? undefined)
}
onClick={runCustomSqlPreview}
data-attr="data-quality-check-test-query"
>
Test query
</LemonButton>
{customSqlPreviewStale && (
<span className="text-secondary text-xs">The query changed since the last test.</span>
)}
</div>
)}
{customSqlPreviewError ? (
<LemonBanner type="error">{customSqlPreviewError}</LemonBanner>
) : !customSqlPreviewLoading && customSqlPreview && customSqlPreviewVerdict ? (
<div className={customSqlPreviewStale ? 'opacity-60' : undefined}>
{customSqlPreview.warnings.length > 0 && (
<LemonBanner type="warning" className="mb-2">
This result may be incomplete or out of date:
<ul className="list-disc pl-5">
{customSqlPreview.warnings.map((warning, index) => (
<li key={index}>{warning.message}</li>
))}
</ul>
</LemonBanner>
)}
{customSqlPreviewVerdict === 'pass' ? (
<LemonBanner type="success">
The query returned no rows. This check would pass.
</LemonBanner>
) : (
<>
<LemonBanner type="warning">
The query returned {customSqlPreview.hasMore ? 'at least ' : ''}
{customSqlPreview.rowCount} rows. This check would fail with{' '}
{customSqlPreview.hasMore ? 'at least ' : ''}
{customSqlPreview.rowCount} failures.
</LemonBanner>
<LemonTable<unknown[]>
className="mt-2"
columns={previewColumns}
dataSource={previewRows}
size="small"
/>
{/* The table caps at 10 rows: flag truncation only when 10 are shown and the
response held more, or the query system reported more beyond them. */}
{previewRows.length === 10 &&
(customSqlPreview.hasMore ||
customSqlPreview.rowCount > previewRows.length) && (
<span className="mt-1 text-secondary text-xs">
Showing the first 10 rows.
</span>
)}
</>
)}
</div>
) : null}
</div>
)}
</LemonField>
)
}
function RelationshipFields(): JSX.Element {
const { checkForm, relationshipSubjects, checkSubjectsLoading, relationshipTargetTimeColumn } =
useValues(dataQualityCheckEditorLogic)
const { setCheckFormValues } = useActions(dataQualityCheckEditorLogic)
const selected = relationshipSubjects.find((subject) => subject.id === checkForm.toSubjectUuid)
return (
<>
<LemonField name="toSubjectUuid" label="References table or view">
<LemonInputSelect
mode="single"
loading={checkSubjectsLoading}
value={checkForm.toSubjectUuid ? [checkForm.toSubjectUuid] : []}
options={relationshipSubjects.map((subject) => ({ key: subject.id, label: subject.name }))}
onChange={(selectedIds) => {
const toSubjectUuid = selectedIds[0]
if (!toSubjectUuid) {
return
}
setCheckFormValues({
toSubjectUuid,
toSubjectType: relationshipSubjects.find((subject) => subject.id === toSubjectUuid)?.type,
toColumn: '',
// The window belongs to the target it was set on, and the field hides
// itself for a target with no time column. A kept value would reach
// the request where nobody can see or clear it.
toLookbackHours: null,
})
}}
/>
</LemonField>
<LemonField name="toColumn" label="References column">
<LemonSelect
disabledReason={selected ? undefined : 'Pick a table or view first'}
options={(selected?.fields ?? []).map((field) => ({ value: field, label: field }))}
/>
</LemonField>
{relationshipTargetTimeColumn ? (
<LemonField
name="toLookbackHours"
label="Only look for a match in recent rows"
showOptional
help={`Hours of ${selected?.name ?? 'the referenced table'} to look in, by ${relationshipTargetTimeColumn}. Leave empty to look in all of it.`}
>
<LemonInput type="number" min={1} placeholder="24" />
</LemonField>
) : null}
</>
)
}
function LookbackField(): JSX.Element | null {
const { checkForm, subjectTimeColumn } = useValues(dataQualityCheckEditorLogic)
if (!subjectTimeColumn || checkForm.checkType === CheckTypeEnumApi.CustomSql) {
return null
}
return (
<LemonField
name="lookbackHours"
label="Only check recent rows"
showOptional
help={`Hours to check, by ${subjectTimeColumn}. Leave empty to check the whole table, which costs more to run.`}
>
<LemonInput type="number" min={1} placeholder="24" />
</LemonField>
)
}