Read It Back

What you'll learn

In SDK v3, GetObject's Body is a stream; turn it into text with transformToString().
Use HeadObject to check that an object exists or to read its size and metadata without downloading it.
Keys are exact and case-sensitive; a missing key is NoSuchKey (or AccessDenied if you can't list the bucket).

Section 01

GetObject returns a stream

Objects can be gigabytes, so the SDK doesn't load the body into memory for you. response.Body is a stream with helper methods:transformToString(), transformToByteArray() and transformToWebStream(). Call one of them once — a stream can only be read once.

Read a JSON cardJavaScript

import { GetObjectCommand } from "@aws-sdk/client-s3";

const res = await client.send(
  new GetObjectCommand({ Bucket: "hoenn-pokedex-media", Key: "cards/0252-treecko.json" })
);
const card = JSON.parse(await res.Body.transformToString());
console.log(res.ContentType, res.Metadata.generation, card.name);

Section 02

HeadObject: metadata only

HeadObject returns the same headers as a GET — ContentLength, ContentType, ETag, LastModified, Metadata — with no body. It's the cheap way to ask “is it there, and how big is it?”

Because a HEAD response has no body, a missing object shows up as a plain NotFound (HTTP 404) rather than NoSuchKey.

Section 03

Byte ranges

Add Range: "bytes=0-1048575" to fetch just the first MiB. S3 answers 206 Partial Content. Video players use ranges to seek, and download tools fetch several ranges in parallel for speed.

Section 04

When the key is wrong

You asked for	You get	Why
`cards/0252-Treecko.json`	`NoSuchKey`	Keys are case-sensitive.
A key that doesn't exist, without s3:ListBucket	`AccessDenied`	S3 won't reveal whether the key exists to callers who can't list the bucket.
An object in a Glacier Flexible or Deep Archive class	`InvalidObjectState`	It must be restored first (Quest 5).

Practice

Your turn

Read Treecko's card back. This code gets a NoSuchKey error and, even with the right key, would log a stream instead of the card. Fix the key and turn the body into an object.

Use the exact key, then await response.Body.transformToString() and JSON.parse it.

// @ts-nocheck
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
const client = new S3Client({ region: "ap-south-1" });
async function readCard() {
  const response = await client.send(
    new GetObjectCommand({
      Bucket: "hoenn-pokedex-media",
      Key: "cards/0252-Treecko.json",
    })
  );
  // ⬇️ response.Body is a stream. Read it as text, then parse the JSON.
  const card = response.Body;
  console.log(card.name, "is type", card.types);
}

// @ts-nocheck
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

const client = new S3Client({ region: "ap-south-1" });

async function readCard() {
  const response = await client.send(
    new GetObjectCommand({
      Bucket: "hoenn-pokedex-media",
      Key: "cards/0252-Treecko.json",
    })
  );

  // ⬇️ response.Body is a stream. Read it as text, then parse the JSON.
  const card = response.Body;
  console.log(card.name, "is type", card.types);
}

Ctrl/⌘ Enter to run · simulated, no AWS callsSimulated — no AWS calls

Check

Check your understanding

Quick Quiz · one question, as many tries as you need.

Your function only needs to know whether a 4 GiB replay exists and how big it is. Which call should it make?

Choose one answer.