---
title: "JSONB Path"
slug: "jsonb-path"
category: "glossary"
tags: ["glossary", "database", "postgres", "jsonb", "jsonpath", "sql"]
status: "stable"
last_updated: 2026-08-14
summary: "JSONB path (jsonpath) navigates and filters nested JSONB in PostgreSQL via a dedicated path language, with optional GIN-index acceleration."
related:
  [
    "[[glossary/gin-index]]",
    "[[glossary/query-plan]]",
    "[[glossary/btree-index]]",
    "[[backend/postgres]]",
    "[[glossary/foreign-data-wrapper]]",
  ]
---

## Overview

This page is the atomic definition. Postgres JSON and indexing guidance lives at [[backend/postgres]]. JSONB path (jsonpath) is a SQL:2016 path language for navigating and filtering nested `jsonb` values, complementing the simpler `->`/`->>`/`@>` operators when queries need array filters or intermediate-node predicates.

## Definition

PostgreSQL stores JSON as `jsonb` (binary-parsed, key-sorted, duplicate-key-eliminated). JSONB supports three query layers:

1. Operators: `->` (get key as jsonb), `->>` (get key as text), `#>` (path as jsonb), `#>>` (path as text), `@>` (containment), `?` (key exists).
2. Containment and existence: `data @> '{"status":"active"}'` -- usable with a GIN index.
3. jsonpath (SQL:2016): `jsonb_path_query(data, '$.items[*] ? (@.price > 100)')` -- a full path language with filters, arithmetic, and accessor chains.

jsonpath functions:
- `jsonb_path_query(jsonb, path)`: returns a set of matching values.
- `jsonb_path_exists(jsonb, path)`: returns boolean; useful in `WHERE`.
- `jsonb_path_match(jsonb, path)`: returns a single boolean for a predicate path.

jsonpath syntax:
- `$` is the root node.
- `.key` accesses an object field.
- `[n]` accesses an array index; `[*]` selects all elements.
- `? (predicate)` is a filter; e.g., `$.orders[*] ? (@.total > 500)`.
- `@` refers to the current node inside a filter.

GIN indexes on the `jsonb` column accelerate containment (`@>`) and key-exists (`?`) operators but do not directly accelerate jsonpath. For jsonpath queries, a GIN index with `jsonb_path_ops` operator class can accelerate path-contains patterns.

## When it applies

Use containment operators (`@>`) for simple key-value matching on JSONB; they are GIN-indexable and concise. Use jsonpath when queries navigate nested arrays or need filters on intermediate nodes. Avoid deeply nested JSONB for data that is queried relationally; normalize to columns or tables where selectivity matters.

## Example

```sql
SELECT id FROM events WHERE data @> '{"type": "click", "page": "/home"}';

SELECT id FROM orders
WHERE jsonb_path_exists(data, '$.items[*] ? (@.total > 100)');

SELECT jsonb_path_query_array(data, '$.items[*].price')
FROM orders WHERE id = 1;

CREATE INDEX idx_events_data ON events USING gin(data jsonb_path_ops);
```

## Related concepts

- [[glossary/gin-index]] - the index type for accelerating JSONB containment and path queries.
- [[glossary/query-plan]] - use `EXPLAIN` to confirm GIN is used for JSONB queries.
- [[glossary/btree-index]] - B-tree can index individual JSONB scalar fields extracted with `->>`.
- [[backend/postgres]] - the Postgres deep-dive.

## Citing this term

> See [[glossary/jsonb-path|JSONB Path]] (llmbestpractices.com/glossary/jsonb-path).

## Related

- [[glossary/gin-index]]
- [[glossary/query-plan]]
- [[glossary/btree-index]]
- [[backend/postgres]]
- [[glossary/foreign-data-wrapper]]