Home / Bases de Datos / Modificar elementos de arrays JSONB en PostgreSQL con SQL puro
Modificar elementos de arrays JSONB en PostgreSQL con SQL puro

Modificar elementos de arrays JSONB en PostgreSQL con SQL puro

17 November 2026 · 23 min de lectura ··

Cuando el array JSONB se convierte en un problema

El tipo JSONB de PostgreSQL resuelve con elegancia una necesidad muy habitual: guardar datos cuya forma cambia de un registro a otro sin crear una tabla nueva cada vez que aparece un atributo. Un proveedor puede tener un teléfono y un correo, otro solo un correo y un tercero tres canales de contacto distintos. Meter todo eso en una columna JSONB es cómodo, rápido de implementar y permite consultar con operadores potentes.

La comodidad desaparece en el momento de modificar un valor concreto que vive dentro de un array. Leer es sencillo: un operador de flecha y listo. Escribir no lo es tanto, porque el valor que quieres cambiar está en una posición que depende del registro. En una fila el correo ocupa la posición cero, en otra la uno y en otra ni siquiera existe. Como no hay una ruta fija, muchos equipos acaban trayendo el documento completo a la aplicación, modificándolo con el lenguaje de turno y devolviéndolo entero a la base de datos. Funciona, pero cada actualización implica un viaje de ida y vuelta, serialización, deserialización y una ventana de tiempo en la que otro proceso puede haber cambiado el mismo registro.

En este tutorial resolveremos el problema dentro de la propia base de datos. Verás cómo localizar la posición de un objeto dentro del array, cómo construir la ruta de forma dinámica, cómo aplicar el cambio con una sola sentencia UPDATE, qué alternativas existen cuando varios elementos cumplen la condición y cómo cuidar el rendimiento y la corrección. Si todavía no manejas con soltura la consola interactiva, conviene repasar antes psql en la terminal, porque todos los ejemplos se pueden ejecutar allí.

Versiones y entorno de pruebas

Los ejemplos funcionan en cualquier versión moderna de PostgreSQL, pero conviene saber en qué punto está el proyecto. La rama estable más reciente es PostgreSQL 18, cuya última versión menor publicada al redactar este texto es la 18.6. La versión 19 se encuentra todavía en fase de candidata a lanzamiento, así que no la usaremos como referencia. La rama 14 deja de recibir correcciones en noviembre de 2026, de modo que si trabajas con ella es un buen momento para planificar una migración.

Las funciones que veremos tienen orígenes distintos. jsonb_set y jsonb_array_elements existen desde hace muchos años. WITH ORDINALITY es estándar SQL y lleva mucho tiempo disponible. La sintaxis de subíndices para JSONB llegó con PostgreSQL 14. Y las funciones del estándar SQL/JSON, como JSON_EXISTS, JSON_QUERY y JSON_VALUE, se incorporaron en la versión 17 junto con JSON_TABLE, que ya permite proyectar un documento JSON como si fuera una tabla. Todo esto está al alcance de PostgreSQL 18.

Para practicar puedes levantar un contenedor desechable. Es la forma más rápida de tener una instancia limpia y destruirla al terminar.

docker run --name pg-jsonb -e POSTGRES_PASSWORD=secreto -p 5432:5432 -d postgres:18
docker exec -it pg-jsonb psql -U postgres

Si prefieres una instalación local, cualquier paquete de PostgreSQL 14 o superior sirve para casi todo lo que sigue. Las secciones que dependen de una versión concreta lo indican de forma explícita.

El escenario: proveedores y sus canales de contacto

Vamos a modelar una tabla de proveedores. Cada uno tiene un identificador, un nombre y una columna JSONB llamada canales que contiene un array de objetos. Cada objeto describe una forma de contacto con un tipo y un valor.

CREATE TABLE proveedores (
    id      serial PRIMARY KEY,
    nombre  text NOT NULL,
    canales jsonb NOT NULL DEFAULT '[]'::jsonb
);

INSERT INTO proveedores (nombre, canales) VALUES
  ('Aurora Logística',
   '[{"tipo": "telefono", "valor": "+34 910 000 111"},
     {"tipo": "correo",   "valor": "[email protected]"}]'),
  ('Brisa Envases',
   '[{"tipo": "correo",   "valor": "[email protected]"}]'),
  ('Cobalto Textil',
   '[{"tipo": "web",      "valor": "https://cobalto.example"},
     {"tipo": "telefono", "valor": "+34 920 222 333"},
     {"tipo": "correo",   "valor": "[email protected]"}]');

Fíjate en que el correo aparece en la posición 1 para Aurora, en la 0 para Brisa y en la 2 para Cobalto. Ese es justamente el obstáculo: no puedes escribir una ruta fija como {1,valor} y esperar que sirva para todos. Necesitamos calcular la posición para cada fila.

Comprobemos el estado inicial con una consulta que muestre el correo de cada proveedor. Aquí aún no actualizamos nada, solo exploramos.

SELECT p.nombre, c.elem ->> 'valor' AS correo
FROM proveedores p
CROSS JOIN LATERAL jsonb_array_elements(p.canales) AS c(elem)
WHERE c.elem ->> 'tipo' = 'correo';
      nombre      |         correo
------------------+-------------------------
 Aurora Logística | [email protected]
 Brisa Envases    | [email protected]
 Cobalto Textil   | [email protected]
(3 rows)

La consulta ya nos da una pista de la técnica: jsonb_array_elements despliega el array en filas y el filtro selecciona el objeto que nos interesa. Lo que nos falta es saber en qué posición estaba.

Por qué conviene actualizar dentro de la base de datos

Antes de entrar en el código vale la pena justificar el esfuerzo. Modificar el documento en la aplicación tiene tres costes que se suelen subestimar.

El primero es el tráfico. Para cambiar un correo de cincuenta caracteres, la aplicación descarga un documento que puede pesar kilobytes y lo vuelve a subir completo. Si el cambio se hace sobre miles de filas, el volumen se multiplica.

El segundo es la concurrencia. Entre la lectura y la escritura transcurre un intervalo en el que otra transacción puede modificar otro campo del mismo documento. Cuando la aplicación escribe, pisa ese cambio sin darse cuenta. Una sentencia UPDATE única evalúa la condición y escribe bajo el mismo bloqueo de fila, lo que cierra esa ventana.

El tercero es la repetición de lógica. Si varios servicios escritos en lenguajes distintos tocan la misma columna, cada uno implementa su propia versión de la transformación, con sus propios errores. Concentrarla en SQL, quizá dentro de una función almacenada, deja una única fuente de verdad.

Con esto no se afirma que la base de datos deba contener toda la lógica de negocio. Se trata de que una operación puramente estructural sobre un documento, como cambiar un valor dentro de un array, pertenece de forma natural a la capa de datos. Si quieres reforzar las nociones previas sobre el modelo relacional y el lenguaje, tienes una introducción en fundamentos de DBMS y SQL.

La función jsonb_set por dentro

La pieza que realiza el cambio es jsonb_set. Su firma es la siguiente.

jsonb_set(objetivo jsonb, ruta text[], nuevo_valor jsonb [, crear_si_falta boolean DEFAULT true])

Recibe el documento original, una ruta expresada como array de texto, el valor nuevo que debe ser un JSONB válido y un indicador opcional que decide si se crea la clave cuando no existe. Devuelve un documento nuevo; no modifica nada por sí misma, de ahí que se use dentro de un UPDATE ... SET.

Veámosla en acción con literales, para entender cómo se interpreta la ruta.

SELECT jsonb_set(
         '[{"tipo":"telefono","valor":"111"},{"tipo":"correo","valor":"[email protected]"}]'::jsonb,
         '{1,valor}',
         '"[email protected]"'
       );
                                 jsonb_set
---------------------------------------------------------------------------
 [{"tipo": "telefono", "valor": "111"}, {"tipo": "correo", "valor": "[email protected]"}]
(1 row)

La ruta {1,valor} significa: entra en el elemento de la posición 1 del array y, dentro de él, en la clave valor. Las posiciones de los arrays JSON empiezan en cero, y esto es importante porque más adelante obtendremos posiciones numeradas desde uno y habrá que corregir la diferencia.

Un detalle que sorprende a casi todos al principio es que el tercer argumento debe ser JSONB, no texto. Si pasas un texto con comillas dobles internas, como en el ejemplo, PostgreSQL lo convierte implícitamente porque el literal es de tipo desconocido. Pero cuando el valor viene de una variable o de una columna de tipo text, la conversión no es automática y hay que aplicar to_jsonb, que se encarga además de escapar las comillas por ti.

SELECT jsonb_set('{"a": 1}'::jsonb, '{a}', to_jsonb('texto con "comillas"'::text));

Un error muy frecuente es construir el valor concatenando cadenas a mano, lo cual rompe el JSON ante cualquier carácter especial y abre la puerta a inyecciones. Usa siempre to_jsonb o parámetros tipados.

Localizar la posición con WITH ORDINALITY

Para construir la ruta necesitamos saber en qué posición está el objeto. jsonb_array_elements devuelve los elementos como filas, pero sin número de orden. La cláusula WITH ORDINALITY añade una columna con la posición de cada fila, empezando en uno.

SELECT p.id, e.pos, e.elem
FROM proveedores p
CROSS JOIN LATERAL jsonb_array_elements(p.canales)
     WITH ORDINALITY AS e(elem, pos)
ORDER BY p.id, e.pos;
 id | pos |                      elem
----+-----+------------------------------------------------
  1 |   1 | {"tipo": "telefono", "valor": "+34 910 000 111"}
  1 |   2 | {"tipo": "correo", "valor": "[email protected]"}
  2 |   1 | {"tipo": "correo", "valor": "[email protected]"}
  3 |   1 | {"tipo": "web", "valor": "https://cobalto.example"}
  3 |   2 | {"tipo": "telefono", "valor": "+34 920 222 333"}
  3 |   3 | {"tipo": "correo", "valor": "[email protected]"}
(6 rows)

Ahora cada objeto lleva su número de orden. El correo de Aurora tiene pos = 2, y como JSON cuenta desde cero, la posición real es 1. Esa resta de una unidad es el detalle que más errores provoca: si te olvidas de ella, modificarás el elemento equivocado o recibirás una ruta que apunta fuera del array.

El uso de CROSS JOIN LATERAL merece una explicación. La palabra LATERAL permite que la función de la derecha haga referencia a columnas de la tabla de la izquierda, en este caso p.canales. Sin ella, la función no podría ver la fila actual. Es el mecanismo estándar para expandir una colección por cada fila, y en el caso de las funciones que devuelven conjuntos, la palabra LATERAL es incluso opcional, aunque escribirla hace la intención más legible.

Construir la ruta de forma dinámica

Con la posición en la mano, la ruta se arma como un array de texto. Hay dos maneras habituales. La primera concatena una cadena con llaves y la convierte a text[].

('{' || (e.pos - 1) || ',valor}')::text[]

La segunda usa el constructor ARRAY, que evita jugar con llaves y comas y resulta más difícil de romper.

ARRAY[(e.pos - 1)::text, 'valor']

Prefiero la segunda porque expresa la estructura de la ruta sin depender del formato de literal de arrays. Si el nombre de la clave tuviera una coma, una llave o un espacio, la versión concatenada exigiría escapes; el constructor no tiene ese problema. Una vez que dominas esta idea, la ruta puede tener tantos niveles como necesites, por ejemplo ARRAY[(e.pos - 1)::text, 'horario', 'apertura'] para entrar a un objeto anidado.

La sentencia UPDATE completa

Juntemos las piezas. Un bloque WITH calcula, para el proveedor elegido, la ruta del objeto de tipo correo. Después el UPDATE utiliza esa ruta dentro de jsonb_set.

WITH objetivo AS (
    SELECT p.id,
           ARRAY[(e.pos - 1)::text, 'valor'] AS ruta
    FROM proveedores p
    CROSS JOIN LATERAL jsonb_array_elements(p.canales)
         WITH ORDINALITY AS e(elem, pos)
    WHERE p.nombre = 'Aurora Logística'
      AND e.elem ->> 'tipo' = 'correo'
    ORDER BY e.pos
    LIMIT 1
)
UPDATE proveedores p
SET canales = jsonb_set(
        p.canales,
        o.ruta,
        to_jsonb('[email protected]'::text)
    )
FROM objetivo o
WHERE p.id = o.id
RETURNING p.nombre, p.canales;
      nombre      |                                         canales
------------------+--------------------------------------------------------------------------------------------
 Aurora Logística | [{"tipo": "telefono", "valor": "+34 910 000 111"}, {"tipo": "correo", "valor": "[email protected]"}]
(1 row)

Tres decisiones de esta consulta merecen comentario. La primera es el LIMIT 1 con ORDER BY e.pos: si un proveedor tuviera dos objetos de tipo correo, la unión del UPDATE ... FROM tomaría una coincidencia arbitraria y el resultado no sería determinista. Al ordenar y limitar, elegimos siempre la primera aparición. La segunda es RETURNING, que devuelve la fila ya modificada y permite verificar el resultado sin lanzar otra consulta. La tercera es que el filtro por nombre está dentro del bloque WITH, de modo que solo se calcula la ruta para la fila deseada y el UPDATE toca únicamente esa fila.

Para ejecutar con seguridad cualquier prueba, envuélvela en una transacción y revierte si el resultado no te convence.

BEGIN;
-- aquí va el UPDATE de arriba
ROLLBACK;

Si prefieres actualizar muchas filas a la vez, basta con quitar el filtro por nombre y el LIMIT 1, y sustituirlo por una selección de una fila por proveedor mediante DISTINCT ON.

WITH objetivo AS (
    SELECT DISTINCT ON (p.id)
           p.id,
           ARRAY[(e.pos - 1)::text, 'valor'] AS ruta
    FROM proveedores p
    CROSS JOIN LATERAL jsonb_array_elements(p.canales)
         WITH ORDINALITY AS e(elem, pos)
    WHERE e.elem ->> 'tipo' = 'correo'
    ORDER BY p.id, e.pos
)
UPDATE proveedores p
SET canales = jsonb_set(p.canales, o.ruta, to_jsonb(lower(p.canales #>> o.ruta)))
FROM objetivo o
WHERE p.id = o.id;

Este ejemplo muestra cómo la ruta calculada se reutiliza para transformar el valor existente, en este caso pasándolo a minúsculas, en lugar de sobrescribirlo con una constante. El operador #>> extrae como texto el valor situado en una ruta, y recibe el mismo array que jsonb_set, lo que hace natural la combinación.

Actualizar todos los objetos que cumplan la condición

La técnica anterior modifica un solo elemento por fila. Hay casos en los que varios objetos del mismo array deben cambiar, por ejemplo marcar como verificados todos los canales de tipo telefónico. Calcular una ruta por cada coincidencia complica el UPDATE, porque habría que aplicar jsonb_set varias veces sobre el mismo documento.

Una alternativa más robusta es reconstruir el array completo. Despliegas los elementos, transformas los que cumplen la condición con un CASE y vuelves a agruparlos con jsonb_agg, preservando el orden gracias a la ordinalidad.

UPDATE proveedores p
SET canales = (
    SELECT jsonb_agg(
             CASE
               WHEN t.elem ->> 'tipo' = 'telefono'
                 THEN t.elem || '{"verificado": true}'::jsonb
               ELSE t.elem
             END
             ORDER BY t.pos
           )
    FROM jsonb_array_elements(p.canales) WITH ORDINALITY AS t(elem, pos)
)
WHERE p.canales @> '[{"tipo": "telefono"}]';

El operador || combina dos objetos JSONB, y si la clave ya existía, el valor del lado derecho prevalece. La cláusula ORDER BY dentro de jsonb_agg garantiza que los elementos conserven su posición original, algo que sin ella no está asegurado. El filtro final con @> evita reescribir proveedores que no tienen ningún teléfono, y de paso puede aprovechar un índice, como veremos al hablar de rendimiento. Es importante mantener ese filtro por otra razón: jsonb_agg sobre un conjunto vacío devuelve NULL, y con la restricción NOT NULL de la columna una fila con array vacío haría fallar la sentencia.

Esta variante es más costosa que la ruta directa, porque reescribe todo el array, pero es más fácil de razonar cuando la condición afecta a varios elementos o cuando el cambio implica lógica condicional. Elegir entre ambas es cuestión de equilibrio: ruta calculada para un único objetivo, reconstrucción para cambios múltiples.

Subíndices JSONB desde PostgreSQL 14

Si ya conoces la posición, o la obtienes de otra manera, la sintaxis de subíndices permite escribir la modificación de forma mucho más compacta, parecida a la de un lenguaje de programación.

UPDATE proveedores
SET canales[1]['valor'] = '"[email protected]"'
WHERE nombre = 'Aurora Logística';

Se lee casi como una asignación a un elemento de una lista. El valor asignado tiene que ser un JSONB válido, de ahí las comillas dobles dentro de las simples. También se puede leer con la misma notación, por ejemplo SELECT canales[1]['tipo'] FROM proveedores.

La notación tiene sus particularidades. Si el elemento intermedio no existe, PostgreSQL lo crea cuando es posible, y si asignas a una posición mayor que la longitud del array, rellena los huecos con valores nulos JSON. Eso puede dejar basura en tus datos si te equivocas de índice. Por ese motivo, en operaciones críticas sigo prefiriendo jsonb_set con crear_si_falta en falso, que falla de forma silenciosa en lugar de inventar estructura.

Ten presente que el subíndice no resuelve el problema central de este tutorial: sigue necesitando conocer la posición. Es útil cuando la posición es fija por convención del modelo, y la ordinalidad sigue siendo la herramienta cuando no lo es.

Buscar con rutas SQL/JSON y funciones del estándar

PostgreSQL incluye desde hace tiempo un lenguaje de rutas, jsonpath, con funciones como jsonb_path_exists y jsonb_path_query. Sirven para localizar datos con expresiones declarativas, aunque no para escribirlos. Un uso práctico es filtrar qué filas necesitan actualización.

SELECT nombre
FROM proveedores
WHERE jsonb_path_exists(canales, '$[*] ? (@.tipo == "correo" && @.valor like_regex "aurora")');

Con PostgreSQL 17 y posteriores puedes usar además las funciones del estándar. JSON_EXISTS comprueba una condición, JSON_VALUE extrae un escalar y JSON_QUERY extrae fragmentos JSON, todas con sintaxis más cercana al SQL tradicional.

SELECT nombre,
       JSON_VALUE(canales, '$[*] ? (@.tipo == "correo").valor' RETURNING text) AS correo
FROM proveedores
WHERE JSON_EXISTS(canales, '$[*] ? (@.tipo == "web")');

Y JSON_TABLE resulta especialmente valioso para obtener la posición de un elemento de forma declarativa, con la cláusula FOR ORDINALITY.

SELECT p.id, jt.posicion, jt.tipo, jt.valor
FROM proveedores p,
     JSON_TABLE(
       p.canales, '$[*]'
       COLUMNS (
         posicion FOR ORDINALITY,
         tipo  text PATH '$.tipo',
         valor text PATH '$.valor'
       )
     ) AS jt
WHERE jt.tipo = 'correo';

Aquí posicion también empieza en uno, igual que con WITH ORDINALITY, por lo que la resta de una unidad sigue siendo necesaria al construir la ruta de jsonb_set. Si tu versión es anterior a la 17, el patrón con jsonb_array_elements sigue siendo perfectamente válido y es el que recomiendo mantener cuando el código debe ejecutarse en varias versiones.

Si trabajas con datos de texto dentro de los JSON y necesitas búsquedas flexibles, puedes combinar estas consultas con técnicas de similitud como las descritas en coincidencia aproximada de cadenas en PostgreSQL, por ejemplo para localizar proveedores cuyo nombre se parece a otro.

Insertar y eliminar elementos del array

El mismo razonamiento de la ruta se aplica a otras operaciones de mantenimiento. Para añadir un elemento al final del array basta con el operador de concatenación.

UPDATE proveedores
SET canales = canales || '{"tipo": "web", "valor": "https://brisa.example"}'::jsonb
WHERE nombre = 'Brisa Envases';

Cuando se concatena un objeto a un array, PostgreSQL lo trata como un elemento nuevo. Si quieres insertar en una posición concreta, existe jsonb_insert, que recibe una ruta y un indicador para insertar antes o después del elemento indicado.

UPDATE proveedores
SET canales = jsonb_insert(canales, '{0}', '{"tipo": "movil", "valor": "+34 600 000 000"}'::jsonb)
WHERE nombre = 'Brisa Envases';

Para eliminar un elemento por posición se usa el operador #- con la ruta, y para eliminar por condición vuelve a ser más natural reconstruir el array con un filtro.

UPDATE proveedores p
SET canales = COALESCE((
    SELECT jsonb_agg(t.elem ORDER BY t.pos)
    FROM jsonb_array_elements(p.canales) WITH ORDINALITY AS t(elem, pos)
    WHERE t.elem ->> 'tipo' <> 'web'
), '[]'::jsonb)
WHERE p.canales @> '[{"tipo": "web"}]';

El COALESCE es imprescindible: si todos los elementos se eliminan, jsonb_agg devuelve NULL y la restricción de la columna fallaría. Sustituirlo por un array vacío mantiene el modelo consistente.

Errores comunes y cómo evitarlos

Después de varios proyectos con este tipo de datos, hay un puñado de fallos que se repiten una y otra vez.

El primero es la resta olvidada. Si usas pos directamente como índice de la ruta, apuntas al elemento siguiente. En un array de tres elementos, el último correo quedaría fuera de rango, y jsonb_set simplemente no hace nada cuando la ruta no existe y crear_si_falta no puede crear la posición. Tu UPDATE reportará una fila afectada y no habrá ningún cambio visible. Siempre verifica con RETURNING.

El segundo es el valor NULL. Si alguno de los argumentos de jsonb_set es nulo, el resultado entero es nulo, y escribirías NULL en la columna. Esto sucede, por ejemplo, cuando la ruta calculada procede de una subconsulta que no encontró coincidencias y se usa dentro de un UPDATE sin cláusula FROM. Por eso el patrón con FROM objetivo es más seguro: si no hay coincidencia, no hay fila que actualizar. Y cuando necesites una escritura condicional dentro de una expresión, protege con COALESCE(jsonb_set(...), canales).

El tercero es confundir json y jsonb. Las funciones que hemos usado trabajan con jsonb; si tu columna es de tipo json, no existe jsonb_set para ella y tendrás que convertir. Además json conserva el texto tal cual, sin índices útiles, y en casi todos los casos nuevos conviene elegir jsonb.

El cuarto es el valor con tipo incorrecto. Pasar un número como texto, o viceversa, deja datos inconsistentes que luego rompen comparaciones. Con to_jsonb(42) guardas un número y con to_jsonb('42'::text) una cadena. Decide cuál quieres y sé coherente.

El quinto es ignorar la unicidad. Nada en JSONB impide tener dos objetos del mismo tipo en un array. Si tu regla de negocio dice que solo existe un correo por proveedor, hazla cumplir, o bien con una restricción CHECK apoyada en una función, o bien eligiendo la normalización. Más adelante tratamos esa decisión.

Rendimiento: lo que ocurre bajo el capó

Es fundamental comprender que, aunque la sintaxis sugiera una modificación puntual, PostgreSQL no edita el JSONB en el sitio. Gracias a su modelo de versiones múltiples, cada UPDATE escribe una versión nueva completa de la fila, incluyendo el documento entero. Un array pequeño apenas se nota, pero un documento de varios cientos de kilobytes, almacenado fuera de línea mediante TOAST, se reescribe por completo en cada cambio. En cargas con muchas actualizaciones de documentos grandes el volumen de escritura y la presión sobre el vacuum crecen de forma notable.

Esto significa que la técnica de este tutorial evita el viaje de red y los problemas de concurrencia, pero no reduce el coste de escritura en disco. Para mantenerlo bajo, mantén los documentos pequeños, separa los datos que cambian con frecuencia de los que no, y vigila la bloat de la tabla.

Para la parte de lectura, los índices GIN sobre columnas JSONB aceleran las consultas con @>, ? y similares. Un índice con la clase de operadores jsonb_path_ops es más pequeño y rápido para contención, aunque soporta menos operadores.

CREATE INDEX idx_proveedores_canales
    ON proveedores USING gin (canales jsonb_path_ops);

Con ese índice, el filtro WHERE canales @> '[{"tipo": "telefono"}]' de las secciones anteriores no necesita recorrer toda la tabla. Pero el índice se actualiza en cada modificación del documento, por lo que añade coste de escritura. No lo crees sin necesidad medida.

Para decidir con datos y no con intuición, usa EXPLAIN (ANALYZE, BUFFERS) sobre tu UPDATE dentro de una transacción que luego revierta. Observarás cuántas filas se tocan, cuánto tarda el cálculo de la ruta y si el índice se utiliza en la fase de búsqueda.

BEGIN;
EXPLAIN (ANALYZE, BUFFERS)
UPDATE proveedores p
SET canales = jsonb_set(p.canales, '{0,valor}', '"x"')
WHERE p.canales @> '[{"tipo": "telefono"}]';
ROLLBACK;

Encapsular la lógica en una función

Si esta operación se repite en varios sitios, conviene empaquetarla en una función reutilizable. Una función SQL que reciba el documento, el tipo buscado y el valor nuevo, y devuelva el documento modificado, deja las consultas de actualización muy legibles.

CREATE OR REPLACE FUNCTION reemplazar_valor_canal(
    doc    jsonb,
    p_tipo text,
    nuevo  text
) RETURNS jsonb
LANGUAGE sql
IMMUTABLE
AS $$
    SELECT COALESCE(
        (SELECT jsonb_set(doc, ARRAY[(e.pos - 1)::text, 'valor'], to_jsonb(nuevo))
         FROM jsonb_array_elements(doc) WITH ORDINALITY AS e(elem, pos)
         WHERE e.elem ->> 'tipo' = p_tipo
         ORDER BY e.pos
         LIMIT 1),
        doc
    );
$$;

La función devuelve el documento original si no existe un objeto del tipo pedido, evitando el problema del resultado nulo. Usarla es inmediato.

UPDATE proveedores
SET canales = reemplazar_valor_canal(canales, 'correo', '[email protected]')
WHERE nombre = 'Cobalto Textil';

Aquí la sentencia expresa la intención de negocio y oculta el detalle de posiciones. Además puedes probar la función de forma aislada con literales, lo que facilita las pruebas automáticas. Marcarla como IMMUTABLE es correcto porque depende solo de sus argumentos.

Concurrencia y consistencia

Una sentencia UPDATE bloquea la fila que modifica hasta el final de la transacción. Si dos sesiones intentan cambiar el mismo proveedor a la vez, la segunda espera a que la primera termine y después reevalúa la condición sobre la versión actualizada de la fila en el nivel de aislamiento por defecto, que es READ COMMITTED. Esto es una gran ventaja frente al patrón de leer, modificar en la aplicación y escribir, que puede perder cambios.

Hay un matiz. La reevaluación afecta a las condiciones de la cláusula WHERE del propio UPDATE, pero no recalcula la ruta de un bloque WITH previo si este se evaluó con una versión anterior de la fila. En el patrón con FROM objetivo, la ruta se determina con la instantánea inicial. Si otra transacción reordena el array en medio, la ruta podría apuntar a otro elemento. Para escenarios con alta concurrencia sobre el mismo documento, prefiere la variante de reconstrucción con jsonb_agg en una sola expresión, o bloquea la fila antes con SELECT ... FOR UPDATE.

BEGIN;
SELECT canales FROM proveedores WHERE nombre = 'Aurora Logística' FOR UPDATE;
-- ahora aplica el UPDATE con la ruta calculada
COMMIT;

Este bloqueo explícito es barato cuando la ventana es corta y elimina la posibilidad de que el array cambie entre el cálculo y la escritura.

Cuándo es mejor normalizar

Todo lo anterior funciona, pero la dificultad que has visto para cambiar un correo es una señal. Si tus consultas actualizan con frecuencia elementos concretos de un array, filtran por ellos o necesitan integridad referencial, quizá el modelo está pidiendo una tabla propia.

Una tabla canales_proveedor con las columnas proveedor_id, tipo y valor convierte la actualización en un UPDATE trivial con una condición. Además permite restricciones de unicidad, claves foráneas, índices ordinarios y estadísticas precisas para el optimizador. Con JSONB, el optimizador conoce muy poco sobre el contenido de los documentos y sus estimaciones de filas son menos fiables.

Una regla razonable es la siguiente. Usa JSONB para datos verdaderamente variables y de lectura mayoritaria, de lectura mayoritaria o que se tratan como un bloque opaco. Usa tablas para datos con estructura estable sobre los que se consulta y escribe de forma granular. Y en situaciones intermedias, mantén columnas relacionales para lo importante, como el identificador, el estado y las fechas, y deja en JSONB solo los atributos opcionales.

Puedes migrar de un modelo a otro de manera incremental. La función jsonb_array_elements te permite poblar la nueva tabla en una sola sentencia.

CREATE TABLE canales_proveedor (
    id           bigserial PRIMARY KEY,
    proveedor_id int NOT NULL REFERENCES proveedores (id),
    tipo         text NOT NULL,
    valor        text NOT NULL,
    UNIQUE (proveedor_id, tipo)
);

INSERT INTO canales_proveedor (proveedor_id, tipo, valor)
SELECT p.id, e.elem ->> 'tipo', e.elem ->> 'valor'
FROM proveedores p
CROSS JOIN LATERAL jsonb_array_elements(p.canales) AS e(elem);

La restricción de unicidad hará fallar la inserción si algún proveedor tiene dos canales del mismo tipo, lo cual te revelará problemas de calidad de datos que el JSONB ocultaba.

Pruebas y verificación de los cambios

Cualquier transformación de documentos debería acompañarse de comprobaciones. Antes de ejecutar un UPDATE masivo en producción, haz una copia de seguridad de la tabla o de las columnas afectadas, y valida el resultado con consultas de control.

Una técnica sencilla es comparar antes y después con la ayuda de una tabla temporal.

CREATE TEMP TABLE respaldo_canales AS
SELECT id, canales FROM proveedores;

-- Ejecuta la actualización...

SELECT p.id, r.canales AS antes, p.canales AS despues
FROM proveedores p
JOIN respaldo_canales r USING (id)
WHERE p.canales IS DISTINCT FROM r.canales;

La comparación IS DISTINCT FROM maneja bien los nulos y el operador de igualdad para JSONB compara el contenido sin importar el orden de las claves. El resultado te muestra exactamente qué filas cambiaron y cómo, y es la base para decidir si confirmas la transacción.

Añade también una restricción de verificación que proteja la forma del documento, por ejemplo exigiendo que la columna sea un array.

ALTER TABLE proveedores
    ADD CONSTRAINT canales_es_array
    CHECK (jsonb_typeof(canales) = 'array');

Con ella, un error en alguna transformación que devolviera un objeto en lugar de un array se detiene en la propia escritura, antes de contaminar los datos.

Resumen de patrones según el caso

Para que puedas elegir rápidamente, estas son las situaciones habituales y la herramienta que mejor encaja.

  • Cambiar un valor de un único objeto cuya posición se desconoce: WITH ORDINALITY, ruta con ARRAY[...] y jsonb_set.
  • Cambiar varios objetos del mismo array: reconstrucción con jsonb_agg y CASE, conservando el orden.
  • Posición conocida y fija: subíndices JSONB.
  • Añadir al final: operador ||. Insertar en posición: jsonb_insert.
  • Eliminar por posición: operador #-. Eliminar por condición: reconstrucción con filtro y COALESCE.
  • Localizar filas: @> con índice GIN, jsonb_path_exists o JSON_EXISTS en versiones recientes.
  • Proyectar el array como tabla: JSON_TABLE desde PostgreSQL 17 o jsonb_array_elements en versiones anteriores.

Las tres primeras técnicas cubren la inmensa mayoría de los casos reales. Las demás completan el ciclo de vida del documento.

Conclusiones

Actualizar un objeto dentro de un array JSONB parece un problema incómodo mientras se piensa en términos de posiciones fijas, pero se vuelve manejable cuando se descompone en pasos pequeños: desplegar el array con WITH ORDINALITY, filtrar el objeto que cumple la condición, convertir su posición en una ruta restando una unidad y aplicar jsonb_set dentro de un único UPDATE. Todo ocurre en el servidor, con un solo bloqueo de fila y sin transportar documentos a la aplicación.

Conviene recordar las trampas principales: la diferencia entre posiciones desde cero y desde uno, el resultado nulo cuando algún argumento falta, la necesidad de convertir los valores con to_jsonb y la posibilidad de varias coincidencias en el mismo array. Para cambios múltiples, la reconstrucción con jsonb_agg es la opción más clara, y los subíndices de PostgreSQL 14 simplifican los casos de posición conocida.

También hay que mantener los pies en el suelo respecto al rendimiento. Cada actualización reescribe el documento completo, por lo que los JSONB grandes y muy modificados pesan en el almacenamiento y en el mantenimiento. Los índices GIN ayudan a buscar, pero cuestan al escribir. Y cuando el patrón de acceso es granular y constante, la mejor solución suele ser salir del JSONB y normalizar. Con PostgreSQL 18 como rama estable actual y las funciones SQL/JSON disponibles desde la 17, tienes un conjunto de herramientas maduro para trabajar con documentos sin renunciar a la solidez del modelo relacional.