Custom Entities (Description)

Describe what you want to detect in plain English. Agent Mask uses an AI model to find matches from your description. For description-only matching, you do not need training data, regex, or lookup tables.

Minimal example

SELECT app_public.mask(
  'Patient prescribed Metformin 500mg and Lisinopril 10mg',
  OBJECT_CONSTRUCT(
    'entity_config', OBJECT_CONSTRUCT(
      'RX_MED', OBJECT_CONSTRUCT(
        'description', 'prescription drug names: Zoloft, Prozac, Ambien, metformin',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[RX_MED]')
      )
    )
  )
);
-- Patient prescribed [RX_MED] 500mg and [RX_MED] 10mg

Key entity_config fields

Field	Required	Description
`description`	Yes	Plain-English description of what to detect. Be specific.
`operator`	No	Operator to apply. Defaults to `type_numbered`.
`operator_params`	No	Per-operator params. See operators.
`threshold`	No	Per-entity confidence threshold. Overrides global.
`validators`	No	Optional regex validators that filter description matches (see below).

Multiple custom entities

You can define multiple description-based entities. Configure each custom type separately; each description targets one type. The term: concrete examples pattern helps the model understand the kind of value you mean and can improve detection:

SELECT app_public.mask(
  intake_note,
  OBJECT_CONSTRUCT(
    'entity_config', OBJECT_CONSTRUCT(
      'MRN', OBJECT_CONSTRUCT(
        'description', 'medical record numbers (MRN)',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[MRN]')
      ),
      'INSURANCE', OBJECT_CONSTRUCT(
        'description', 'health insurance: plan names, group numbers',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[INSURANCE]')
      ),
      'RX_MED', OBJECT_CONSTRUCT(
        'description', 'prescription drug names: Zoloft, Prozac, Ambien, metformin',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[RX_MED]')
      ),
      'DOSAGE', OBJECT_CONSTRUCT(
        'description', 'medication dosages: 50mg BID, 10mg IV push, 500mg TID',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[DOSAGE]')
      ),
      'MENTAL_DX', OBJECT_CONSTRUCT(
        'description', 'psychiatric diagnoses: schizophrenia, OCD, anorexia, ADHD',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[MENTAL_DX]')
      ),
      'GENETIC', OBJECT_CONSTRUCT(
        'description', 'genetic markers and test results: BRCA2, HER2, Lynch syndrome',
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[GENETIC]')
      )
    )
  )
) FROM app_public.sample_records WHERE record_id = 1;

Filter matches with validators

Add regex validators when the description should find candidates, but the final value must also match a required format. All validators on an entity must pass.

SELECT app_public.mask(
  'Q3 reconciliation: invoice INV-600078 cleared, invoice 4500 still pending review.',
  OBJECT_CONSTRUCT(
    'entity_config', OBJECT_CONSTRUCT(
      'INVOICE_NUMBER', OBJECT_CONSTRUCT(
        'description', 'company invoice identifiers',
        'validators', ARRAY_CONSTRUCT(
          OBJECT_CONSTRUCT('pattern', '^INV-\\d{6}$', 'mode', 'full')
        ),
        'operator', 'constant',
        'operator_params', OBJECT_CONSTRUCT('value', '[INVOICE]')
      )
    )
  )
);
-- Q3 reconciliation: invoice [INVOICE] cleared, invoice 4500 still pending review.

Validator modes:

"full" — the whole entity text must match.
"partial" — any part of the entity must match.

If you only need pattern-based detection, use custom entities (regex). Validators are best when you still want semantic detection but need to reject spans that do not match a required format.

Tips for good descriptions

Describe what it IS, not what it isn’t: positive framing usually gives the model a clearer target. "prescription drug names: Zoloft, Prozac, Ambien" is clearer than "drugs excluding OTC supplements".
Include concrete examples: the term: example1, example2, example3 pattern is often clearer than abstract definitions. "genetic markers: BRCA2, HER2, Lynch syndrome" is more specific than "genetic test results".
Be specific: "psychiatric diagnoses: schizophrenia, OCD, ADHD" beats "mental health conditions".
Iterate on threshold: start at the default 0.5, then tune per-entity if you see too many false positives or misses.

Limitations

Description-based entities are semantic detectors. They can miss ambiguous mentions or include nearby text, and they do not verify external facts such as whether a drug, plan, or code belongs to a specific official catalog. Use regex custom entities, validators, allow_list, thresholds, and representative sample review when exact matching matters.