Comprehend via SDK Best Practices

Q: What's the single most common mistake with Comprehend?

Treating DetectPiiEntities output as already-redacted text. It only returns types, scores, and offsets - your code (or the async job's redaction mode) does the actual masking.

Q: What IAM setup does a batch job need that a synchronous call doesn't?

A DataAccessRoleArn Comprehend can assume to read your input S3 prefix and write your output S3 prefix. Synchronous calls only need the caller's own permission to invoke the operation.

Q: How should I handle low-confidence detections?

Apply a consistent minimum Score threshold and route anything below it to a fallback or human review path, rather than trusting a marginal result the same as a high-confidence one.

This is the checklist to run before and after taking a Comprehend workload to production from the SDK.

Each item is a rule stated positively, with a one-line rationale. Work top to bottom - the groups run from language and input handling, through the real-time-vs-batch decision, to PII/security, custom models, cost, and operations. Most rules apply whether you call Comprehend from boto3 or the AWS SDK v3.

How to Use This List

Treat each box as an audit question against your own project.
The groups run roughly from correctness of input, through cost-shaping decisions, to security and operations.
Most rules hold regardless of which pretrained or custom Comprehend capability you're calling.
Revisit the list whenever you add a new document type, a new language, or a custom model.

A - Language & Input Handling

Detect language before scoring text of unknown origin. Run DetectDominantLanguage first and feed its result into LanguageCode for DetectSentiment/DetectEntities - a wrong code degrades accuracy without raising an error.
Chunk documents that exceed the per-call size limit. Split by paragraph or sentence boundary and track cumulative offsets, rather than truncating or erroring on long input.
Treat offsets as character positions, not tokens. BeginOffset/EndOffset index into the exact string you sent - slice that same string to recover the matched substring.
Don't reformat text between detection and rendering. Stripping whitespace or translating after calling Detect invalidates the offsets returned for the original string.

Detect language first whenever the input source isn't guaranteed to be one language.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Merci pour votre reponse rapide."
 
# Detect language before scoring - a wrong LanguageCode silently hurts accuracy.
top = max(comprehend.detect_dominant_language(Text=text)["Languages"], key=lambda l: l["Score"])
sentiment = comprehend.detect_sentiment(Text=text, LanguageCode=top["LanguageCode"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectDominantLanguageCommand, DetectSentimentCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Merci pour votre reponse rapide.";
 
// Detect language before scoring - a wrong LanguageCode silently hurts accuracy.
const langs = (await comprehend.send(new DetectDominantLanguageCommand({ Text: text }))).Languages ?? [];
const top = langs.reduce((a, b) => (b.Score! > a.Score! ? b : a));
const sentiment = await comprehend.send(new DetectSentimentCommand({ Text: text, LanguageCode: top.LanguageCode }));

B - Choosing Real-Time vs Batch

Default to batch (Start*Job) when nothing is waiting on an immediate answer. It's typically cheaper to operate and avoids a client-side loop over many synchronous calls.
Reserve synchronous Detect calls for live, per-request logic. A user submitting a comment or a live chat message is the right fit for sub-second latency.
Don't loop synchronous calls over a large document set. Once a client-side loop starts reimplementing job management, switch to the matching Start*Job.
Poll Describe*Job on a sane interval with a timeout. There is no push notification for job completion - a tight polling loop wastes calls without speeding anything up.

C - PII & Security

Never treat DetectPiiEntities output as redacted text. It returns types, scores, and offsets only - masking the text is your code's job, or use the async job's ONLY_REDACTION mode.
Mask matched spans from the end of the string backward. Masking earlier matches first shifts every later offset and corrupts subsequent masks.
Gate full PII detection with ContainsPiiEntities at high volume. It's a cheaper check that tells you whether the fuller, offset-returning call is worth running.
Never log a DetectPiiEntities response alongside the source text. The offsets plus the original text reconstruct the exact sensitive substrings.
Scope IAM narrowly for batch jobs. DataAccessRoleArn should read only the specific input prefix and write only the specific output prefix, not a whole bucket.

Redact from offsets working backward so earlier positions stay valid.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Contact Dana at dana@example.com."
entities = comprehend.detect_pii_entities(Text=text, LanguageCode="en")["Entities"]
 
# Mask from the end backward so earlier offsets don't shift.
redacted = text
for e in sorted(entities, key=lambda e: e["BeginOffset"], reverse=True):
    redacted = redacted[:e["BeginOffset"]] + f"[{e['Type']}]" + redacted[e["EndOffset"]:]

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectPiiEntitiesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Contact Dana at dana@example.com.";
const entities = (await comprehend.send(new DetectPiiEntitiesCommand({ Text: text, LanguageCode: "en" }))).Entities ?? [];
 
// Mask from the end backward so earlier offsets don't shift.
let redacted = text;
for (const e of [...entities].sort((a, b) => b.BeginOffset! - a.BeginOffset!)) {
  redacted = redacted.slice(0, e.BeginOffset) + `[${e.Type}]` + redacted.slice(e.EndOffset);
}

D - Custom Models

Reach for Comprehend Custom only when pretrained models genuinely miss your domain. Training and hosting cost time and money the pretrained Detect APIs don't.
Poll training status instead of assuming CreateDocumentClassifier/CreateEntityRecognizer is synchronous. Both return an ARN immediately and train in the background; wait for Status: TRAINED.
Prefer a batch job over a real-time endpoint for custom-model inference unless traffic is continuous. Batch calls the model ARN directly with no hourly-billed endpoint.
Keep prior model versions briefly during a rollout. Each training call produces a new ARN, so you can compare or roll back before fully switching over.
Check per-label/per-entity-type example counts before training. Too few or unbalanced examples are the most common cause of a weak or IN_ERROR model.

E - Cost Control

Delete unused real-time endpoints. They bill by the hour for provisioned inference units whether or not they receive traffic.
Batch process archives instead of looping live calls over them. One job call plus IAM setup beats thousands of individually billed, individually retried synchronous requests.
Gate expensive calls behind cheaper pre-checks. Use ContainsPiiEntities before DetectPiiEntities, and language detection before committing to a downstream call, to avoid wasted processing on the wrong path.
Avoid re-running full detection on unchanged documents. Cache or track which documents have already been processed before re-scanning a corpus.

F - Operations & Reliability

Reuse one Comprehend client across calls. A shared client reuses the connection pool and resolved credentials, cutting overhead versus creating one per call.
Branch explicitly on every terminal JobStatus. Handle COMPLETED, FAILED, and STOPPED distinctly rather than only checking for success.
Verify DataAccessRoleArn trust and permissions before relying on a batch job. A misconfigured trust policy or missing S3 permissions is the most common first-batch-job failure.
Apply a consistent confidence threshold across entities, key phrases, and PII. All three return a Score; decide and document your minimum bar rather than filtering inconsistently across call sites.
Treat low-confidence results as "uncertain," not "wrong." Route borderline sentiment, language, or PII detections to a fallback or review path instead of trusting a marginal score outright.

FAQs

What's the single most common mistake with Comprehend?

Treating DetectPiiEntities output as already-redacted text. It only returns types, scores, and offsets - your code (or the async job's redaction mode) does the actual masking.

Should I always detect language before scoring sentiment?

Yes, whenever the input's language isn't already known with certainty. A wrong LanguageCode doesn't error - it silently applies the wrong language model and degrades accuracy.

Is batch or real-time the safer default?

Batch, whenever nothing is waiting on an immediate answer. It's typically cheaper to operate and, for custom models, avoids paying for an hourly real-time endpoint between runs.

How do I avoid surprise custom-model costs?

Delete real-time endpoints you're not actively using - they bill hourly regardless of traffic - and prefer batch jobs for custom-model inference unless traffic is continuous.

What IAM setup does a batch job need that a synchronous call doesn't?

A DataAccessRoleArn Comprehend can assume to read your input S3 prefix and write your output S3 prefix. Synchronous calls only need the caller's own permission to invoke the operation.

How should I handle low-confidence detections?

Apply a consistent minimum Score threshold and route anything below it to a fallback or human review path, rather than trusting a marginal result the same as a high-confidence one.

When is it finally worth training a custom model?

When you can point at specific documents the pretrained Detect APIs consistently mislabel or miss - not before. Training and, for real-time use, hosting cost more than the pretrained calls.

Comprehend's Managed NLP Model Surface - the pretrained-vs-custom, real-time-vs-batch map these rules assume.
PII Detection & Redaction - the detect-then-redact rules in group C.
Custom Classification & Custom Entity Recognition - the training and hosting habits in group D.
Batch vs Real-Time Comprehend Jobs - the decision behind group B.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Comprehend via SDK Best Practices

This is the checklist to run before and after taking a Comprehend workload to production from the SDK.

How to Use This List

Treat each box as an audit question against your own project.
The groups run roughly from correctness of input, through cost-shaping decisions, to security and operations.
Most rules hold regardless of which pretrained or custom Comprehend capability you're calling.
Revisit the list whenever you add a new document type, a new language, or a custom model.

A - Language & Input Handling

Detect language before scoring text of unknown origin. Run DetectDominantLanguage first and feed its result into LanguageCode for DetectSentiment/DetectEntities - a wrong code degrades accuracy without raising an error.
Chunk documents that exceed the per-call size limit. Split by paragraph or sentence boundary and track cumulative offsets, rather than truncating or erroring on long input.
Treat offsets as character positions, not tokens. BeginOffset/EndOffset index into the exact string you sent - slice that same string to recover the matched substring.
Don't reformat text between detection and rendering. Stripping whitespace or translating after calling Detect invalidates the offsets returned for the original string.

Detect language first whenever the input source isn't guaranteed to be one language.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Merci pour votre reponse rapide."
 
# Detect language before scoring - a wrong LanguageCode silently hurts accuracy.
top = max(comprehend.detect_dominant_language(Text=text)["Languages"], key=lambda l: l["Score"])
sentiment = comprehend.detect_sentiment(Text=text, LanguageCode=top["LanguageCode"])

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectDominantLanguageCommand, DetectSentimentCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Merci pour votre reponse rapide.";
 
// Detect language before scoring - a wrong LanguageCode silently hurts accuracy.
const langs = (await comprehend.send(new DetectDominantLanguageCommand({ Text: text }))).Languages ?? [];
const top = langs.reduce((a, b) => (b.Score! > a.Score! ? b : a));
const sentiment = await comprehend.send(new DetectSentimentCommand({ Text: text, LanguageCode: top.LanguageCode }));

B - Choosing Real-Time vs Batch

Default to batch (Start*Job) when nothing is waiting on an immediate answer. It's typically cheaper to operate and avoids a client-side loop over many synchronous calls.
Reserve synchronous Detect calls for live, per-request logic. A user submitting a comment or a live chat message is the right fit for sub-second latency.
Don't loop synchronous calls over a large document set. Once a client-side loop starts reimplementing job management, switch to the matching Start*Job.
Poll Describe*Job on a sane interval with a timeout. There is no push notification for job completion - a tight polling loop wastes calls without speeding anything up.

C - PII & Security

Never treat DetectPiiEntities output as redacted text. It returns types, scores, and offsets only - masking the text is your code's job, or use the async job's ONLY_REDACTION mode.
Mask matched spans from the end of the string backward. Masking earlier matches first shifts every later offset and corrupts subsequent masks.
Gate full PII detection with ContainsPiiEntities at high volume. It's a cheaper check that tells you whether the fuller, offset-returning call is worth running.
Never log a DetectPiiEntities response alongside the source text. The offsets plus the original text reconstruct the exact sensitive substrings.
Scope IAM narrowly for batch jobs. DataAccessRoleArn should read only the specific input prefix and write only the specific output prefix, not a whole bucket.

Redact from offsets working backward so earlier positions stay valid.

# --- Python (boto3) ---
import boto3
 
comprehend = boto3.client("comprehend")
text = "Contact Dana at dana@example.com."
entities = comprehend.detect_pii_entities(Text=text, LanguageCode="en")["Entities"]
 
# Mask from the end backward so earlier offsets don't shift.
redacted = text
for e in sorted(entities, key=lambda e: e["BeginOffset"], reverse=True):
    redacted = redacted[:e["BeginOffset"]] + f"[{e['Type']}]" + redacted[e["EndOffset"]:]

// --- TypeScript (AWS SDK v3) ---
import { ComprehendClient, DetectPiiEntitiesCommand } from "@aws-sdk/client-comprehend";
 
const comprehend = new ComprehendClient({});
const text = "Contact Dana at dana@example.com.";
const entities = (await comprehend.send(new DetectPiiEntitiesCommand({ Text: text, LanguageCode: "en" }))).Entities ?? [];
 
// Mask from the end backward so earlier offsets don't shift.
let redacted = text;
for (const e of [...entities].sort((a, b) => b.BeginOffset! - a.BeginOffset!)) {
  redacted = redacted.slice(0, e.BeginOffset) + `[${e.Type}]` + redacted.slice(e.EndOffset);
}

D - Custom Models

Reach for Comprehend Custom only when pretrained models genuinely miss your domain. Training and hosting cost time and money the pretrained Detect APIs don't.
Poll training status instead of assuming CreateDocumentClassifier/CreateEntityRecognizer is synchronous. Both return an ARN immediately and train in the background; wait for Status: TRAINED.
Prefer a batch job over a real-time endpoint for custom-model inference unless traffic is continuous. Batch calls the model ARN directly with no hourly-billed endpoint.
Keep prior model versions briefly during a rollout. Each training call produces a new ARN, so you can compare or roll back before fully switching over.
Check per-label/per-entity-type example counts before training. Too few or unbalanced examples are the most common cause of a weak or IN_ERROR model.

E - Cost Control

Delete unused real-time endpoints. They bill by the hour for provisioned inference units whether or not they receive traffic.
Batch process archives instead of looping live calls over them. One job call plus IAM setup beats thousands of individually billed, individually retried synchronous requests.
Gate expensive calls behind cheaper pre-checks. Use ContainsPiiEntities before DetectPiiEntities, and language detection before committing to a downstream call, to avoid wasted processing on the wrong path.
Avoid re-running full detection on unchanged documents. Cache or track which documents have already been processed before re-scanning a corpus.

F - Operations & Reliability

Reuse one Comprehend client across calls. A shared client reuses the connection pool and resolved credentials, cutting overhead versus creating one per call.
Branch explicitly on every terminal JobStatus. Handle COMPLETED, FAILED, and STOPPED distinctly rather than only checking for success.
Verify DataAccessRoleArn trust and permissions before relying on a batch job. A misconfigured trust policy or missing S3 permissions is the most common first-batch-job failure.
Apply a consistent confidence threshold across entities, key phrases, and PII. All three return a Score; decide and document your minimum bar rather than filtering inconsistently across call sites.
Treat low-confidence results as "uncertain," not "wrong." Route borderline sentiment, language, or PII detections to a fallback or review path instead of trusting a marginal score outright.

FAQs

What's the single most common mistake with Comprehend?

Treating DetectPiiEntities output as already-redacted text. It only returns types, scores, and offsets - your code (or the async job's redaction mode) does the actual masking.

Should I always detect language before scoring sentiment?

Yes, whenever the input's language isn't already known with certainty. A wrong LanguageCode doesn't error - it silently applies the wrong language model and degrades accuracy.

Is batch or real-time the safer default?

Batch, whenever nothing is waiting on an immediate answer. It's typically cheaper to operate and, for custom models, avoids paying for an hourly real-time endpoint between runs.

How do I avoid surprise custom-model costs?

Delete real-time endpoints you're not actively using - they bill hourly regardless of traffic - and prefer batch jobs for custom-model inference unless traffic is continuous.

What IAM setup does a batch job need that a synchronous call doesn't?

A DataAccessRoleArn Comprehend can assume to read your input S3 prefix and write your output S3 prefix. Synchronous calls only need the caller's own permission to invoke the operation.

How should I handle low-confidence detections?

Apply a consistent minimum Score threshold and route anything below it to a fallback or human review path, rather than trusting a marginal result the same as a high-confidence one.

When is it finally worth training a custom model?

When you can point at specific documents the pretrained Detect APIs consistently mislabel or miss - not before. Training and, for real-time use, hosting cost more than the pretrained calls.

Comprehend's Managed NLP Model Surface - the pretrained-vs-custom, real-time-vs-batch map these rules assume.
PII Detection & Redaction - the detect-then-redact rules in group C.
Custom Classification & Custom Entity Recognition - the training and hosting habits in group D.
Batch vs Real-Time Comprehend Jobs - the decision behind group B.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Comprehend via SDK Best Practices

Search Documentation

Comprehend via SDK Best Practices