Amazon Comprehend for beginners: language, mood and personal data from one command

Amazon Comprehend, in plain words

Amazon Comprehend is a natural language processing (NLP) service. You send it text and it answers with JSON: the dominant language, the overall sentiment (positive, negative, neutral or mixed), targeted sentiment for each thing mentioned, entities such as people, places and dates, key phrases, the part of speech of each word, and personally identifiable information (PII) such as names, emails and phone numbers. Every answer carries a confidence score between 0 and 1.

There is no model to pick, train or host for the built-in features. The real-time APIs, such as DetectSentiment, take one document and answer within the same call, and batch versions take up to 25 documents at once. For large piles of files in S3 there are asynchronous jobs, and Comprehend Custom lets you train your own classifiers and entity recognizers when the built-in labels don't fit. You pay per 100 characters analyzed, with a minimum of 300 characters per request.

One change to know about: since April 30, 2026, three Comprehend features (topic modeling, event detection and prompt safety classification) are no longer open to new customers. AWS points people to Amazon Bedrock models for the first two and to Bedrock Guardrails for prompt safety. The features in today's lab are not affected.

The AI angle

Comprehend uses pre-trained, single-purpose models, so it is often the cheap first pass in front of a generative AI app: detect the language to choose a prompt, score sentiment to route angry tickets first, or find PII with DetectPiiEntities and mask it before the text reaches a Bedrock model or a Knowledge Base. If the PII check sits right at the model call, Bedrock Guardrails has its own sensitive information filters that can block or mask PII in both prompts and responses, so compare the two before building both.

Hands-on lab: Ask Comprehend about four short texts and mask the personal details

From AWS CloudShell, detect a language, score overall and per-item sentiment, find PII in a made-up message and print a masked copy. No AWS resources are created; you only make a handful of real-time API calls.

1. Open CloudShell and write the sample texts

   Choose the CloudShell icon in the console's top bar. These lines set the Region and save two made-up product reviews to a local file, one review per line. Nothing is created in AWS. If CloudShell restarts, run this step again.

   REGION=us-east-1
   cat > reviews.txt <<'EOF'
   The headphones sound great and the battery lasts all week.
   The case cracked after two days and support never answered my email.
   EOF
   cat reviews.txt

   Done

2. Which language is this?

   detect-dominant-language needs no language code; it works one out. The answer is a list sorted by confidence, so the first entry is the dominant language. You should see es with a high score.

   aws comprehend detect-dominant-language --region "$REGION" \
     --text "Hoy hace un día precioso y el parque está lleno de gente." \
     --query 'Languages[0]'

   Done

3. Score the overall mood of each review

   detect-sentiment returns one label for the whole text plus a score for each of the four possible labels. The loop sends each line of the file as its own request (two requests in total).

   while IFS= read -r LINE; do
     echo "$LINE"
     aws comprehend detect-sentiment --region "$REGION" \
       --language-code en --text "$LINE" \
       --query '[Sentiment, SentimentScore.Positive, SentimentScore.Negative]' \
       --output text
   done < reviews.txt

   Done

4. Score the mood per thing mentioned

   A mixed review hides detail inside one label. detect-targeted-sentiment finds the entities and gives each mention its own sentiment. Expect the pizza to come back positive and the delivery negative, each with a type such as COMMERCIAL_ITEM or OTHER.

   aws comprehend detect-targeted-sentiment --region "$REGION" \
     --language-code en \
     --text "The pizza was delicious but the delivery took two hours." \
     --query 'Entities[].Mentions[].[Text, Type, MentionSentiment.Sentiment]' \
     --output table

   Done

5. Find the personal details and mask them

   detect-pii-entities returns each PII item's type and its start and end character positions; it does not change your text. The loop uses those positions to print each item and to build a copy with every item replaced by # characters. The message is made up and uses a reserved example domain and a fictional 555 number.

   TEXT="Hi, this is Jordan Rivera. Email me at jordan.rivera@example.com or call 555-0100 about my order."
   aws comprehend detect-pii-entities --region "$REGION" \
     --language-code en --text "$TEXT" \
     --query 'Entities[].[Type, BeginOffset, EndOffset]' --output text > pii.txt
   MASKED="$TEXT"
   while read -r TYPE B E; do
     LEN=$((E - B))
     echo "$TYPE -> ${TEXT:$B:$LEN}"
     MASKED="${MASKED:0:$B}$(printf '%*s' "$LEN" '' | tr ' ' '#')${MASKED:$E}"
   done < pii.txt
   echo "$MASKED"

   Done

rm -f reviews.txt pii.txt
ls reviews.txt pii.txt
aws comprehend list-sentiment-detection-jobs --region "$REGION" \
  --query 'SentimentDetectionJobPropertiesList[].JobId'

Gotchas

• Every request is billed for at least 300 characters, so sending one tweet at a time costs the same as sending 300 characters. For many short texts, the batch APIs take up to 25 documents per call.
• Size limits differ by API: sentiment and targeted sentiment accept up to 5 KB of text per request, while PII, key phrases and dominant language accept up to 100 KB.
• The CLI reference lists the same 12 language codes for most commands, but the developer guide is narrower for some features: real-time PII detection for English and Spanish, targeted sentiment for English only. Check the feature page before relying on another language.
• Real-time PII detection finds and locates PII but doesn't redact it. A redacted copy comes from an asynchronous job, or from your own code using the offsets as in step 5. Scores are confidence values, not guarantees, so review results before trusting them with regulated data.
• If your account never used topic modeling, event detection or prompt safety classification in the 12 months before the April 30, 2026 change, those features are closed to you. Older tutorials that use them won't work in a new sandbox account.