Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/agents/frontend.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,19 @@ values; negative text conditions do not include empty values. Private fields
such as notes are scoped to the current user's joined row. The field mapping
and parameterized compiler live in `api/board/column_filters.py`.

A field whose values are a known set is picked, not typed. `any_of` and
`none_of` take a JSON array in `value`: OR within the condition, AND across
conditions, and `none_of` is the exclusion. Text fields compare them
case-insensitively and whole. The `place` field matches the classified
`locations` rows, never the raw text: a pick is `remote` or
`COUNTRY[/REGION[/CITY]]` (REGION may be empty), and a country takes every
region and city in it, by jsonb containment on `locations.places`. A location
not yet classified matches no pick. Offer picks from the list's
`facets.place` and `facets.company` (on `with_facets=true`), which count the
board under every other condition except the field's own, so a selected pick
never hides its siblings. Labels are the client's: country codes through
`Intl.DisplayNames`.

**A refusal is `{detail: {code, message, ...}}`, built by `api.problem.refuse`.**
`code` is what a client branches on and stays stable; `message` is for a
person and may be reworded. Extra keys (a `task_id`, the `in_flight` run) ride
Expand Down
41 changes: 38 additions & 3 deletions openapi.json
Original file line number Diff line number Diff line change
Expand Up @@ -37346,7 +37346,7 @@
"anyOf": [
{
"type": "string",
"maxLength": 1000
"maxLength": 4000
},
{
"type": "null"
Expand Down Expand Up @@ -39178,6 +39178,24 @@
],
"title": "ExtensionConfig"
},
"FacetValue": {
"properties": {
"value": {
"type": "string",
"title": "Value"
},
"count": {
"type": "integer",
"title": "Count"
}
},
"type": "object",
"required": [
"value",
"count"
],
"title": "FacetValue"
},
"Facets": {
"properties": {
"ats": {
Expand All @@ -39186,14 +39204,30 @@
},
"type": "array",
"title": "Ats"
},
"place": {
"items": {
"$ref": "#/components/schemas/FacetValue"
},
"type": "array",
"title": "Place",
"default": []
},
"company": {
"items": {
"$ref": "#/components/schemas/FacetValue"
},
"type": "array",
"title": "Company",
"default": []
}
},
"type": "object",
"required": [
"ats"
],
"title": "Facets",
"description": "Counts under every OTHER filter the page has on. Taken before the ats\nclause joins the rest, because a board-wide \"rippling 4\" beside a lens\nthat holds none of them reads as a lie."
"description": "Counts under every OTHER filter the page has on. Taken before the ats\nclause joins the rest, because a board-wide \"rippling 4\" beside a lens\nthat holds none of them reads as a lie. `place` and `company` likewise\nleave out their own column conditions, so a pick never hides its siblings.\n\nA `place` value is a pick the place column filter takes: \"remote\", or\n\"COUNTRY\", \"COUNTRY/REGION\", \"COUNTRY/REGION/CITY\" (REGION may be empty)."
},
"FailedCheck": {
"properties": {
Expand Down Expand Up @@ -39847,7 +39881,8 @@
"text",
"date",
"number",
"boolean"
"boolean",
"place"
],
"title": "Kind"
},
Expand Down
201 changes: 138 additions & 63 deletions src/api/board/column_filters.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@ class ColumnFilter(BaseModel):
model_config = ConfigDict(extra="forbid")
field: str
operator: str
value: str | None = Field(default=None, max_length=1000)
# A list operator (any_of, none_of) carries a JSON array here.
value: str | None = Field(default=None, max_length=4000)


FilterKind = Literal["text", "date", "number", "boolean"]
FilterKind = Literal["text", "date", "number", "boolean", "place"]


class FilterField(BaseModel):
Expand All @@ -30,18 +31,30 @@ class FilterField(BaseModel):
operators: list[str]


_LIST_OPERATORS = ("any_of", "none_of")
_OPERATORS = {
"text": ["contains", "not_contains", "equals", "not_equals", "is_empty", "is_not_empty"],
"text": [
"contains",
"not_contains",
"equals",
"not_equals",
"any_of",
"none_of",
"is_empty",
"is_not_empty",
],
"date": ["equals", "gte", "lte", "is_empty", "is_not_empty"],
"number": ["equals", "gte", "lte", "is_empty", "is_not_empty"],
"boolean": ["equals"],
"place": list(_LIST_OPERATORS),
}
_FIELDS: dict[str, tuple[str, FilterKind, str]] = {
# Trimmed so `equals` reads lower(btrim(company)), which idx_jobs_company_key
# serves: untrimmed, an exact company on the 1.1M-row catalog walked the
# primary key for 5 s; trimmed, 0.4 s (2026-10-15).
"company": ("Company", "text", "btrim(j.company)"),
"title": ("Role", "text", "j.title"),
"place": ("Location", "place", ""),
"locations": ("Location text", "text", "array_to_string(j.locations, ', ')"),
"terms": ("Employment terms", "text", "array_to_string(j.terms, ', ')"),
"source": ("Source", "text", "j.source"),
Expand Down Expand Up @@ -98,66 +111,128 @@ def compile_filters(
if not isinstance(values, list) or len(values) > 32:
raise ValueError("Supply at most 32 column filters")
rules = [ColumnFilter.model_validate(value) for value in values]
offered = _offered(catalog_only)
clauses, params = [], {}
for index, rule in enumerate(rules):
if rule.field not in offered:
raise ValueError(f"Unknown filter field: {rule.field}")
_, kind, expression = offered[rule.field]
if rule.operator not in _OPERATORS[kind]:
raise ValueError(f"Unsupported operator for {rule.field}")
if rule.operator in ("is_empty", "is_not_empty"):
if rule.value is not None:
raise ValueError("Empty-value operators do not take a value")
empty = (
f"NULLIF(btrim({expression}), '') IS NULL"
if kind == "text"
else f"{expression} IS NULL"
)
clauses.append(
f"AND ({empty})" if rule.operator == "is_empty" else f"AND NOT ({empty})"
)
continue
if rule.value is None or not rule.value.strip():
raise ValueError(f"A value is required for {rule.field}")
name = f"column_filter_{index}"
value: object = rule.value
if rule.operator in ("not_equals", "not_contains"):
clauses.append(f"AND NULLIF(btrim({expression}), '') IS NOT NULL")
if kind == "date":
value = datetime.date.fromisoformat(rule.value)
elif kind == "number":
value = Decimal(rule.value)
if not value.is_finite():
raise ValueError("Pay must be a finite number")
if abs(value) > Decimal("1e18"):
raise ValueError("Pay value exceeds the supported numeric range")
units = {r.field: r.value for r in rules if r.operator == "equals"}
if (
not units.get("comp_currency")
or canonical_compensation_period(units.get("comp_period")) is None
):
raise ValueError("Pay comparisons require an exact currency and pay period")
elif rule.field == "comp_period" and rule.operator in ("equals", "not_equals"):
value = canonical_compensation_period(rule.value) or rule.value
elif kind == "boolean":
if rule.value not in ("true", "false"):
raise ValueError("Boolean filters accept true or false")
value = rule.value == "true"
if rule.operator in ("contains", "not_contains"):
value = (
"%"
+ rule.value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+ "%"
)
op = "ILIKE" if rule.operator == "contains" else "NOT ILIKE"
else:
op = {"equals": "=", "not_equals": "<>", "gte": ">=", "lte": "<="}[rule.operator]
if kind == "text" and rule.operator in ("equals", "not_equals"):
clauses.append(f"AND lower({expression}) {op} lower(%({name})s)")
else:
clauses.append(f"AND {expression} {op} %({name})s")
params[name] = value
clauses, params = compile_rules(rules, catalog_only)
return rules, clauses, params
except (ValueError, ArithmeticError) as error:
raise refuse(422, "INVALID_COLUMN_FILTER", str(error)) from error


# A place pick is "remote" or "COUNTRY[/REGION[/CITY]]", the levels of a
# `locations.places` entry. The facet (api.routers.job_board) serves the same
# spelling, so a pick is always one the board can count.
REMOTE = "remote"


def place_json(token: str) -> str:
"""The `places` entry a pick contains, as JSON for jsonb containment: a
country pick matches every region and city in it."""
country, region, city = ([*token.split("/", 2), "", ""])[:3]
if len(country) != 2 or not country.isalpha():
raise ValueError(f"Unknown place: {token}")
entry = {"country": country.upper()}
if region:
entry["region"] = region.upper()
if city:
entry["city"] = city
return json.dumps([entry])


def _list_value(rule: ColumnFilter) -> list[str]:
try:
values = json.loads(rule.value or "")
except ValueError:
values = None
if (
not isinstance(values, list)
or not values
or not all(isinstance(v, str) and v.strip() for v in values)
):
raise ValueError(f"{rule.field} {rule.operator} takes a JSON list of values")
return [v.strip() for v in values]


def _place_clause(rule: ColumnFilter, name: str, params: dict) -> str:
picks = _list_value(rule)
params[f"{name}_remote"] = any(p.lower() == REMOTE for p in picks)
params[f"{name}_places"] = [place_json(p) for p in picks if p.lower() != REMOTE]
# Same join as the board criteria (api.board.criteria): a string not yet
# classified has no row and matches nothing.
match = f"""EXISTS (
SELECT 1 FROM unnest(j.locations) loc
JOIN locations l ON l.text = btrim(loc)
WHERE (%({name}_remote)s AND l.remote)
OR l.places @> ANY(%({name}_places)s::text[]::jsonb[]))"""
return f"AND {match}" if rule.operator == "any_of" else f"AND NOT {match}"


def compile_rules(rules: list[ColumnFilter], catalog_only: bool) -> tuple[list[str], dict]:
"""AND of the rules as SQL clauses over `j`, `uj` and `pay`. Raises
ValueError for a rule the endpoint does not offer."""
offered = _offered(catalog_only)
clauses: list[str] = []
params: dict = {}
for index, rule in enumerate(rules):
if rule.field not in offered:
raise ValueError(f"Unknown filter field: {rule.field}")
_, kind, expression = offered[rule.field]
if rule.operator not in _OPERATORS[kind]:
raise ValueError(f"Unsupported operator for {rule.field}")
name = f"column_filter_{index}"
if kind == "place":
clauses.append(_place_clause(rule, name, params))
continue
if rule.operator in _LIST_OPERATORS:
params[name] = [v.lower() for v in _list_value(rule)]
match = f"lower({expression}) = ANY(%({name})s)"
clauses.append(f"AND {match}" if rule.operator == "any_of" else f"AND NOT {match}")
continue
if rule.operator in ("is_empty", "is_not_empty"):
if rule.value is not None:
raise ValueError("Empty-value operators do not take a value")
empty = (
f"NULLIF(btrim({expression}), '') IS NULL"
if kind == "text"
else f"{expression} IS NULL"
)
clauses.append(
f"AND ({empty})" if rule.operator == "is_empty" else f"AND NOT ({empty})"
)
continue
if rule.value is None or not rule.value.strip():
raise ValueError(f"A value is required for {rule.field}")
value: object = rule.value
if rule.operator in ("not_equals", "not_contains"):
clauses.append(f"AND NULLIF(btrim({expression}), '') IS NOT NULL")
if kind == "date":
value = datetime.date.fromisoformat(rule.value)
elif kind == "number":
value = Decimal(rule.value)
if not value.is_finite():
raise ValueError("Pay must be a finite number")
if abs(value) > Decimal("1e18"):
raise ValueError("Pay value exceeds the supported numeric range")
units = {r.field: r.value for r in rules if r.operator == "equals"}
if (
not units.get("comp_currency")
or canonical_compensation_period(units.get("comp_period")) is None
):
raise ValueError("Pay comparisons require an exact currency and pay period")
elif rule.field == "comp_period" and rule.operator in ("equals", "not_equals"):
value = canonical_compensation_period(rule.value) or rule.value
elif kind == "boolean":
if rule.value not in ("true", "false"):
raise ValueError("Boolean filters accept true or false")
value = rule.value == "true"
if rule.operator in ("contains", "not_contains"):
value = (
"%" + rule.value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") + "%"
)
op = "ILIKE" if rule.operator == "contains" else "NOT ILIKE"
else:
op = {"equals": "=", "not_equals": "<>", "gte": ">=", "lte": "<="}[rule.operator]
if kind == "text" and rule.operator in ("equals", "not_equals"):
clauses.append(f"AND lower({expression}) {op} lower(%({name})s)")
else:
clauses.append(f"AND {expression} {op} %({name})s")
params[name] = value
return clauses, params
Loading
Loading