Response Format

mask() returns a VARIANT containing parsed JSON. The examples below show the fields callers can receive from the public SQL function.

Top-level shape

{
  "columns": [...],
  "entity_ledger": [...]
}

columns

Array with one entry per input text. For the STRING overload, exactly one entry. For the ARRAY overload, one entry per array element.

entity_ledger

Array of every detected entity with its original value, placeholder token, and final replacement. Shared across all columns in a single call.

columns[] entries

{
  "index": 0,
  "deidentified_text": "[PERSON_1] lives at [LOCATION_1]",
  "analyzer_results": [
    {
      "entity_type": "PERSON",
      "start": 0,
      "end": 11,
      "score": 0.97
    }
  ]
}

Field	Type	Description
index	INT	Zero-based position of this column in the input array.
deidentified_text	STRING	The masked output text.
analyzer_results	ARRAY	Span-level detection details.
original_text	STRING	Original input (documents only — for documents, input is base64-encoded so the readable text lives here).
document_metadata	OBJECT	Extracted document metadata such as file type, page count, image dimensions, or OCR confidence.
redacted_document	STRING	Base64-encoded, zlib-compressed de-identified file (when include_redacted_document=true).
redaction_metadata	OBJECT	Pixel redaction audit data when include_redaction_metadata=true.

If include_analyzer_results=false, analyzer_results is omitted.

analyzer_results[] entries

Field	Type	Description
entity_type	STRING	The detected type (e.g., PERSON, US_SSN, or your custom entity name).
start	INT	Character offset of the entity in the original text.
end	INT	End offset (exclusive).
score	FLOAT	Detection confidence 0.0–1.0.

entity_ledger[] entries

{
  "entity_type": "PERSON",
  "original": "John Smith",
  "placeholder": "[REDACTED_PERSON_1]",
  "replacement": "[PERSON_1]"
}

Field	Type	Description
entity_type	STRING	Type of the detected entity.
original	STRING	Exact source text that was detected.
placeholder	STRING	Detection placeholder token ([REDACTED_PERSON_1]). Reported in the ledger only; use replacement to match the value written to deidentified_text.
replacement	STRING	Actual text that appears in deidentified_text. For the default type_numbered operator this is [PERSON_1]; for faker, hash, encrypt, or constant it is the operator output.
seeded	BOOLEAN (conditional)	Present (true) only on entries whose binding came from ledger_seed. Absence means the entry was bound in this request.
canonical_original	STRING (conditional)	Present only on entries merged into another by identity resolution: the canonical value this alias was grouped under. Absence means this entry is the canonical value, or no merge occurred.

Output text contains replacement

deidentified_text contains the final replacement value, not the ledger-only placeholder token. For the default type_numbered operator, the replacement is [PERSON_1]; for faker, hash, encrypt, or constant, it is the operator output. Consumers should read replacement instead of scanning output text for [REDACTED_...].

The ledger emits detected entries only. ledger_seed entries that never appeared in the row are omitted; compare the returned ledger with the seed you supplied to find unused seed entries. Pass-through cases where the operator left the value unchanged by design, such as date_shift on relative phrases, time-only values, bare years, or month-year values, are also omitted; keep operator entries are always emitted because cataloging is their purpose.

Row-level warnings[]

Present only when non-empty. Carries row-level processing signals, including SEED_REMAPPED_BY_COLLAPSE records (see identity resolution). The include_* flags do not control warnings.

Archive columns

ZIP inputs return an archive-shaped column instead of deidentified_text at the column level:

{
  "index": 0,
  "archive": {
    "documents": [
      {
        "filename": "note.txt",
        "deidentified_text": "Patient [PERSON_1]",
        "metadata": {"file_type": "txt"},
        "original_text": "Patient Jane Smith"
      }
    ],
    "skipped_files": [
      {"filename": "binary.dat", "reason": "Unsupported file type"}
    ]
  }
}

When include_redacted_document=true, archive document entries that support binary redaction can include redacted_document. If at least one entry has a redacted binary, archive.redacted_archive contains a base64-encoded ZIP with those redacted files.

Redaction metadata

For PDF, image, and DICOM pixel redaction, include_redaction_metadata=true adds:

{
  "entities_redacted": 2,
  "coordinate_system": "pixels",
  "bounding_boxes": [
    {"left": 120, "top": 80, "width": 210, "height": 32, "page": 0, "entity_type": "PERSON"}
  ]
}

page is zero-based. Single-image inputs use page 0.

Returned SQL value

app_public.mask() returns the parsed JSON VARIANT shown in this reference. Callers do not need to decode a binary payload before reading fields such as columns, entity_ledger, or error.

Error shape

When a row-level processing error occurs, the row result has an error object and an empty columns array:

{
  "error": {
    "message": "Failed to preprocess text: invalid document",
    "code": 400
  },
  "columns": []
}

When app_public.mask() rejects the call before row processing, such as an expired trial, the top-level response is:

{
  "error": "7-day trial expired. Contact the provider for continued access."
}