JSONB in Postgres: when a JSON column is the right call, and the index that makes it fast
When to store data as jsonb in Postgres, how containment with @> works, how to choose between the two GIN operator classes, and the row-lock trap.

Eventually, you'll need a column where the data shape changes: customer-specific settings, webhook payloads, or extra form fields. Postgres has a good answer in jsonb. It also has a few details that decide whether that answer stays fast.
Everything below comes from the PostgreSQL documentation page on JSON types.
json or jsonb
Postgres has two JSON types, and the difference matters.
jsonkeeps an exact copy of the input text, including whitespace, key order and duplicate keys. Functions have to reparse it each time.jsonbstores a decomposed binary form. It is slightly slower to write, but much faster to process, and it can be indexed. It does not keep whitespace, key order or duplicate keys; if a key repeats, only the last value is kept.
The documentation's recommendation is to prefer jsonb for most applications, unless you have specialized needs such as depending on key order. The rest of this post assumes jsonb.
When a JSON column is a good fit
The documentation says JSON is more flexible than the relational model, and that both can live in one application. It also adds a caution: even when you want flexibility, documents should keep a somewhat fixed structure. The structure is usually not enforced, but a predictable one makes queries over many documents much easier to write.
A good rule of thumb is:
- Use normal columns for values you filter, join, sort or constrain on in most queries.
- Use jsonb for the part that really varies, or that you mostly read back whole.
- If you find yourself querying the same JSON key everywhere, it has probably earned a column.
The docs describe a good document as an atomic datum: something the business rules say should not be split into smaller pieces that change independently. A customer's notification settings fit. A list of every order a customer ever placed does not.
Querying with containment
The operator you will use most is containment, @>. It asks whether the left document contains the right one.
CREATE TABLE events (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
payload jsonb NOT NULL
);
SELECT id
FROM events
WHERE payload @> '{"type": "signup", "plan": "pro"}';
The rule is: the contained object must match the containing one in structure and data, ignoring extra array elements or key-value pairs in the containing object. A few of its examples show the corners:
SELECT '[1, 2, 3]'::jsonb @> '[3, 1]'::jsonb; -- true, array order does not matter
SELECT '[1, 2, [1, 3]]'::jsonb @> '[1, 3]'::jsonb; -- false, nesting must match
SELECT '[1, 2, [1, 3]]'::jsonb @> '[[1, 3]]'::jsonb; -- true
SELECT '["foo", "bar"]'::jsonb @> '"bar"'::jsonb; -- true, an array may contain a primitive
SELECT '"bar"'::jsonb @> '["bar"]'::jsonb; -- false, and not the other way round
The nesting rule catches people. If your data has an array of objects, your search document needs the same shape.
Indexing: two GIN choices
A plain B-tree index does not help with @>. A GIN index does, and jsonb offers two operator classes.
-- default: jsonb_ops
CREATE INDEX events_payload_idx ON events USING GIN (payload);
-- smaller, narrower: jsonb_path_ops
CREATE INDEX events_payload_path_idx ON events USING GIN (payload jsonb_path_ops);
jsonb_ops (default) |
jsonb_path_ops |
|
|---|---|---|
@> containment |
yes | yes |
@? and @@ (jsonpath) |
yes | yes |
?, ?|, ?& (key exists) |
yes | no |
| Index size | larger | usually much smaller |
| Search speed | good | usually more specific and faster |
The documentation adds one more difference. jsonb_path_ops makes no index entries for structures without values, such as {"a": {}}, so a search for those needs a full index scan, which it calls quite slow.
The decision rule:
- If you need to ask "does this key exist?", use the default.
- If you only use
@>(and jsonpath), tryjsonb_path_opsfirst for the smaller, faster index. - Do not build both unless you can show you need both. Every index adds cost to writes, as covered in how database indexes speed up reads, and when they slow down writes.
Tip
Check that the planner uses your index with
EXPLAIN ANALYZE, as described in reading EXPLAIN ANALYZE. On a tiny table it may still choose a sequential scan, and that is fine.
The row-lock trap
This one is easy to miss. The documentation says JSON data follows the same concurrency rules as any other type, and that any update takes a row-level lock on the whole row. Large documents are practical to store, but if many transactions update the same row's document, they queue behind each other.
So keep documents a manageable size. A counter or a growing list that many requests touch at once does not belong inside one jsonb value. Give those their own rows.
A checklist before you ship
- Is
jsonbused, notjson? - Do the columns you filter and join on most live outside the JSON?
- Does each document keep a fairly fixed structure?
- Is there one GIN index, and does the query shape (
@>only, or key-exists too) match its operator class? - Are documents small enough that updates to one row will not pile up?
- Did you run
EXPLAIN ANALYZEon a realistic amount of data?
If most answers are yes, the flexible column should stay manageable.


