jsonb_pretty formatea un valor JSONB con sangria y saltos de linea, convirtiendo un documento denso de una sola linea en texto legible. Es una herramienta para el ojo humano: depurar en psql, revisar datos y registros, no para almacenar ni transportar.
Uso basico
La funcion recibe un unico valor jsonb y devuelve text con sangria de dos espacios por nivel de anidamiento. Compara la forma compacta y la expandida del mismo documento.
SELECT jsonb_pretty('{"name":"Ana","country":"ES","roles":["admin","ops"]}');
La salida se reparte en lineas y se lee de un vistazo:
{
"name": "Ana",
"roles": [
"admin",
"ops"
],
"country": "ES"
}
Fijate en que country queda despues de roles. JSONB no conserva el orden original de las claves, algo que veremos mas abajo.
Inspeccionar documentos reales
Supongamos que users tiene una columna profile jsonb con ajustes y metadatos. Sin formato, una fila en psql parece un muro de texto. Con jsonb_pretty, cada clave queda en su propia linea.
SELECT u.id, jsonb_pretty(u.profile) AS profile
FROM users u
WHERE u.country = 'ES'
ORDER BY u.created_at DESC
LIMIT 5;
Brilla al revisar agregados. Construye los pedidos de un usuario en un solo documento y mirralo directamente:
SELECT jsonb_pretty(
jsonb_agg(
jsonb_build_object(
'order_id', o.id,
'amount', o.amount,
'status', o.status
) ORDER BY o.created_at
)
) AS orders
FROM orders o
WHERE o.user_id = 42;
Asi resulta facil confirmar que la agregacion y jsonb_build_object producen exactamente la estructura que esperas antes de entregarla a una aplicacion.
Orden de claves y normalizacion
Al analizar, JSONB descarta espacios y claves duplicadas (gana la ultima) y no conserva el orden. Internamente las claves se guardan ordenadas primero por longitud y, a igual longitud, por valor de byte. jsonb_pretty las imprime en ese mismo orden interno, sin reordenar nada por su cuenta, asi que la salida a veces sorprende.
SELECT jsonb_pretty('{"z":1,"a":2,"aa":3}');
Aqui es facil equivocarse. Por longitud, las claves de un caracter a y z van antes que la de dos caracteres aa. Dentro de la longitud 1, el desempate no lo decide el alfabeto en si, sino el valor de byte: a es el codigo 0x61 y z es el codigo 0x7a, de modo que a va antes que z. El orden de salida es por tanto a, z, aa, y no z, a, aa como podrias suponer leyendo las claves de izquierda a derecha. Para letras ASCII en minuscula el orden de bytes coincide con el alfabeto, pero en cuanto aparecen digitos, mayusculas o caracteres no ASCII esa intuicion se rompe y hay que razonar segun los codigos reales de los caracteres.
Esta propiedad no es evidente pero resulta muy util: estabiliza los diffs. Dos documentos logicamente iguales dan una salida formateada identica byte a byte sin importar el orden de escritura, lo que ayuda al comparar el JSON esperado contra el real en pruebas mediante un diff de texto plano. Si de verdad necesitas el orden original de las claves, JSONB no te lo devolvera nunca: para eso esta el tipo json (sin la b), que guarda el texto tal cual llego pero paga un coste de reanalisis en cada acceso.
Cuando no usarlo
El error clasico es meter jsonb_pretty en la ruta de datos de produccion.
- Almacenamiento. Nunca escribas el resultado de
jsonb_pretty de vuelta en una columna. JSONB ya es binario; la sangria es text, bytes extra y un tipo perdido. Guarda jsonb compacto.
- Transporte. Para APIs y colas, emite
row_to_json o un ::text compacto. La sangria infla la carga util y el cliente no la necesita.
- Rendimiento. Formatea por fila. No envuelvas con ella escaneos pesados de millones de filas, solo depuracion puntual con
LIMIT.
Trampa: el resultado es text, no jsonb. Si aplicas jsonb_pretty y luego intentas filtrar con ->> o @>, la expresion falla con un error de tipo. Filtra primero sobre jsonb y formatea al final, solo para mostrar.
Diferencias en otras bases de datos
- MySQL. Sin un nombre identico, pero
JSON_PRETTY(doc) es la funcion incorporada que hace lo mismo para el tipo JSON.
- ClickHouse. Analitica orientada a columnas sin una funcion pretty por expresion para JSON; para una salida legible eliges un formato de salida del cliente (por ejemplo
FORMAT PrettyJSONEachRow) en lugar de una funcion en la proyeccion.
En resumen: jsonb_pretty es una comodidad para el desarrollador. Usala en un SELECT durante la depuracion manual en psql y en informes, pero manten compactos los datos en tus columnas y canales.
jsonb_prettyformatea un valor JSONB con sangria y saltos de linea, convirtiendo un documento denso de una sola linea en texto legible. Es una herramienta para el ojo humano: depurar en psql, revisar datos y registros, no para almacenar ni transportar.Uso basico
La funcion recibe un unico valor
jsonby devuelvetextcon sangria de dos espacios por nivel de anidamiento. Compara la forma compacta y la expandida del mismo documento.SELECT jsonb_pretty('{"name":"Ana","country":"ES","roles":["admin","ops"]}');La salida se reparte en lineas y se lee de un vistazo:
Fijate en que
countryqueda despues deroles. JSONB no conserva el orden original de las claves, algo que veremos mas abajo.Inspeccionar documentos reales
Supongamos que
userstiene una columnaprofile jsonbcon ajustes y metadatos. Sin formato, una fila en psql parece un muro de texto. Conjsonb_pretty, cada clave queda en su propia linea.SELECT u.id, jsonb_pretty(u.profile) AS profile FROM users u WHERE u.country = 'ES' ORDER BY u.created_at DESC LIMIT 5;Brilla al revisar agregados. Construye los pedidos de un usuario en un solo documento y mirralo directamente:
SELECT jsonb_pretty( jsonb_agg( jsonb_build_object( 'order_id', o.id, 'amount', o.amount, 'status', o.status ) ORDER BY o.created_at ) ) AS orders FROM orders o WHERE o.user_id = 42;Asi resulta facil confirmar que la agregacion y
jsonb_build_objectproducen exactamente la estructura que esperas antes de entregarla a una aplicacion.Orden de claves y normalizacion
Al analizar, JSONB descarta espacios y claves duplicadas (gana la ultima) y no conserva el orden. Internamente las claves se guardan ordenadas primero por longitud y, a igual longitud, por valor de byte.
jsonb_prettylas imprime en ese mismo orden interno, sin reordenar nada por su cuenta, asi que la salida a veces sorprende.SELECT jsonb_pretty('{"z":1,"a":2,"aa":3}');Aqui es facil equivocarse. Por longitud, las claves de un caracter
ayzvan antes que la de dos caracteresaa. Dentro de la longitud 1, el desempate no lo decide el alfabeto en si, sino el valor de byte:aes el codigo 0x61 yzes el codigo 0x7a, de modo queava antes quez. El orden de salida es por tantoa,z,aa, y noz,a,aacomo podrias suponer leyendo las claves de izquierda a derecha. Para letras ASCII en minuscula el orden de bytes coincide con el alfabeto, pero en cuanto aparecen digitos, mayusculas o caracteres no ASCII esa intuicion se rompe y hay que razonar segun los codigos reales de los caracteres.Esta propiedad no es evidente pero resulta muy util: estabiliza los diffs. Dos documentos logicamente iguales dan una salida formateada identica byte a byte sin importar el orden de escritura, lo que ayuda al comparar el JSON esperado contra el real en pruebas mediante un diff de texto plano. Si de verdad necesitas el orden original de las claves, JSONB no te lo devolvera nunca: para eso esta el tipo
json(sin lab), que guarda el texto tal cual llego pero paga un coste de reanalisis en cada acceso.Cuando no usarlo
El error clasico es meter
jsonb_prettyen la ruta de datos de produccion.jsonb_prettyde vuelta en una columna. JSONB ya es binario; la sangria estext, bytes extra y un tipo perdido. Guardajsonbcompacto.row_to_jsono un::textcompacto. La sangria infla la carga util y el cliente no la necesita.LIMIT.Diferencias en otras bases de datos
JSON_PRETTY(doc)es la funcion incorporada que hace lo mismo para el tipoJSON.FORMAT PrettyJSONEachRow) en lugar de una funcion en la proyeccion.En resumen:
jsonb_prettyes una comodidad para el desarrollador. Usala en unSELECTdurante la depuracion manual en psql y en informes, pero manten compactos los datos en tus columnas y canales.