Entities

Entities are the labels Agent Mask detects before an operator replaces, masks, hashes, encrypts, or keeps the value. Entity settings decide what is eligible for transformation; operators decide what the replacement looks like.

The same entity configuration works in Snowflake and self-hosted deployments. You can use built-in entity types, add custom entities, restrict detection to a smaller set, tune thresholds, and group aliases when related mentions should share one replacement.

Start here

• Built-in Entity Types — common PII, PHI, financial, HR, and document identifiers
• Custom Entities (Description) — detect domain-specific concepts with plain-English descriptions
• Custom Entities (Regex) — add pattern-based detectors with optional validation
• Supported Languages — language codes and multilingual behavior
• Identity Resolution — group aliases such as “Sarah Chen”, “Chen”, and “Dr. Chen”

Basic example

Omit entities to use the default entity set. Add entities when a workflow should only look for specific types:

SELECT app_public.mask(
  'Patient Jane Smith called 555-0100.',
  OBJECT_CONSTRUCT(
    'entities', ARRAY_CONSTRUCT('PERSON', 'PHONE_NUMBER'),
    'include_analyzer_results', TRUE
  )
);

Use entity_config when a type needs a different operator, threshold, or custom definition:

SELECT app_public.mask(
  'Case RX-4491 belongs to Jane Smith.',
  OBJECT_CONSTRUCT(
    'entity_config', OBJECT_CONSTRUCT(
      'CASE_ID', OBJECT_CONSTRUCT(
        'expressions', ARRAY_CONSTRUCT('RX-[0-9]{4}'),
        'score', 0.9,
        'operator', 'type_numbered'
      ),
      'PERSON', OBJECT_CONSTRUCT('operator', 'mask')
    )
  )
);

Choosing entity settings

• Start with built-in entity types when the data contains common identifiers such as names, emails, dates, phone numbers, addresses, account numbers, or healthcare identifiers.
• Use description-based custom entities for domain concepts that are easier to describe in plain English than to match with a regular expression, such as project names, incident categories, or team role labels.
• Use regex custom entities for structured identifiers with predictable formats, such as ticket IDs, claim numbers, or account codes.
• Tune thresholds on representative samples. Lower thresholds catch more possible entities but can add false positives; higher thresholds are more selective but can miss ambiguous values.
• Enable identity resolution when aliases such as a full name, surname, and title should share one placeholder in the same request.

Review guidance and limits

Detection can miss ambiguous values and can also flag text that is not sensitive. Review samples with include_analyzer_results=true and the entity_ledger before applying a configuration broadly.

Treat response metadata as sensitive. entity_ledger can include detected source values, and analyzer_results can include span details from the original text.

Identity resolution can help keep aliases together, but it may not group every reference to the same person, organization, or location correctly. Review the ledger when identity consistency matters.

For full parameter details, see Request Parameters. For response fields, see Response format.