Leer y escribir contenido
Dentro del servidor no hay HTTP de por medio. Astro.locals.cms habla con D1 directamente, tipado con tus
propias colecciones:
---export const prerender = false
const { docs, pagination } = await Astro.locals.cms.collections.posts.find({ where: { status: { equals: 'published' } }, sort: '-publishedAt', limit: 10,})---
<h1>{pagination.totalDocs} artículos</h1>{docs.map((post) => <a href={`/blog/${post.slug}`}>{post.title}</a>)}prerender = false en toda página que lea contenido: en build no hay bindings de Cloudflare y no hay
nada que leer. Quien pone ahí locals.cms es la integración de Astro.
Esta lectura funciona sin sesión porque posts declara access: { read: 'public' }. locals.cms es
anónimo por defecto: una llamada que no dice quién la hace lanza UnauthorizedError en una
colección sin read: 'public' y en toda escritura. Ver Control de acceso.
Es la misma API que usan por dentro la API REST y el administrador. Siete operaciones:
| Operación | Devuelve | Si no existe |
|---|---|---|
find(args?) |
Una página con sus totales | Una página vacía |
findByID(id, args?) |
El documento | Lanza NotFoundError |
findOne(args?) |
El primero del orden | null |
count(args?) |
Un número | 0 |
create(data) |
El documento creado | — |
update(id, data) |
El documento actualizado | Lanza NotFoundError |
delete(id) |
El documento borrado | Lanza NotFoundError |
findByID lanza y findOne devuelve null a propósito: son dos intenciones distintas, buscar algo que
sabes que está o mirar a ver si está.
Todas aceptan, además, { user, overrideAccess }: en el objeto de argumentos de las lecturas y como
último argumento de las escrituras. Dicen quién llama, y el control de
acceso decide con eso. Sin ellas, la llamada es
anónima.
Las siete son de una colección. Un global —la cabecera, el pie, el SEO: un
documento único sin listado— cuelga de Astro.locals.cms.globals.<slug> y tiene dos, get() y
update(), porque vive en KV y no en D1.
Si la colección declara hooks, corren dentro de la operación, y cada una corre los suyos:
| Operación | Qué hooks corre |
|---|---|
find, findByID, findOne |
afterRead, una vuelta por documento y después de depth |
count |
Ninguno: no devuelve documentos |
create |
beforeValidate → beforeChange → escritura → afterChange → afterRead sobre la respuesta |
update |
Los mismos cuatro, con originalDoc y previousDoc del documento de antes |
delete |
beforeDelete antes de tocar D1, afterDelete con la fila que desapareció |
El orden exacto dentro de cada uno —y dónde entran los hooks de campo— está en Hooks.
Filtrar
Sección titulada «Filtrar»where es un objeto de campos y operadores, y se anida con and y or:
await cms.collections.posts.find({ where: { and: [ { status: { equals: 'published' } }, { publishedAt: { less_than: new Date() } }, { or: [{ title: { contains: 'astro' } }, { author: { in: ['user-1', 'user-2'] } }] }, ], },})La lista completa de operadores y de qué tipos admite cada uno está en la referencia.
Un campo de varios valores (hasMany) se filtra con
los mismos operadores, contra cualquiera de sus valores: ver más abajo.
Un campo que no existe en la colección lanza QueryError, no se ignora. Un filtro que desaparece en
silencio devuelve documentos de más, y eso se descubre tarde y en producción. Lo mismo vale para un operador
que no aplica al tipo del campo: contains sobre un checkbox no filtra nada útil, y like sobre un json
busca dentro de un blob serializado y parece que funciona hasta que no.
contains y like no son lo mismo
Sección titulada «contains y like no son lo mismo»like respeta los comodines de SQL. contains los escapa y envuelve el valor en %…%:
{ excerpt: { contains: '50%' } } // encuentra el texto literal «50%»{ excerpt: { like: '50%' } } // encuentra todo lo que empieza por «50»Un buscador de la web va con contains siempre: si no, cualquiera puede escribir % en tu caja de búsqueda
y traerse la tabla entera.
Valores en crudo
Sección titulada «Valores en crudo»Un where escrito en una plantilla trae valores de verdad — un Date, un number, un boolean. El mismo
where armado desde una query string trae cadenas. Las dos formas filtran igual:
{ publishedAt: { greater_than: new Date('2026-01-01') } }{ publishedAt: { greater_than: '2026-01-01' } } // idéntico{ featured: { equals: 'true' } } // idéntico a `true`La conversión es solo del where. Lo que se guarda y lo que se lee lo convierte el schema generado, en una
única capa: ver Campos.
Ordenar y paginar
Sección titulada «Ordenar y paginar»find() // ORDER BY createdAt DESC, id DESCfind({ sort: 'title' }) // ORDER BY title ASC, id ASCfind({ sort: '-a,b' }) // ORDER BY a DESC, b ASC, id ASCAl orden que pidas siempre se le añade id como último criterio. No es cosmético: createdAt tiene
resolución de milisegundos, y dos documentos creados en el mismo milisegundo se ordenarían de forma
arbitraria entre una página y la siguiente, repitiendo unos y saltándose otros. Como el id es un UUID v7,
ordenar por él es ordenar por instante de creación, así que el desempate además significa algo.
find devuelve las filas en docs y todo lo demás en pagination:
const { docs, pagination } = await cms.collections.posts.find({ limit: 20, page: 2 })
pagination.totalDocs // 42pagination.totalPages // 3pagination.hasNextPage // trueVan juntos en un solo objeto porque casi siempre se pasan juntos: <Paginador {...pagination} /> es todo lo
que necesita un componente para pintarse.
limit es un entero entre 1 y 1000, page un entero mayor o igual que 1, y cualquier otra cosa es
QueryError — también el limit: 0 que en otros CMS significa «todos». En D1 una lectura sin techo es la
forma más fácil de agotar el Worker. Una page más allá del final no es un error: devuelve docs: []
con los totales correctos.
El conteo no cuesta un segundo viaje: las filas y el COUNT(*) van en el mismo batch(), que además es
atómico, así que el total corresponde exactamente a la página devuelta.
Traer solo unas columnas
Sección titulada «Traer solo unas columnas»const { docs } = await cms.collections.posts.find({ select: ['title', 'slug'] })// ^ docs: { id: string, title: string, slug: string }[]El tipo de retorno se estrecha con lo que pidas. id entra siempre, lo pidas o no.
Un subcampo de un group se pide por su ruta con puntos, y se filtra y se
ordena igual que un campo suelto:
await cms.collections.pages.find({ where: { 'seo.metaTitle': { equals: 'A' } }, sort: '-seo.metaTitle', select: ['title', 'seo.metaTitle'],})// docs: { id, title, seo: { metaTitle } }[]El tipo de retorno de un select por ruta no se estrecha: seo sigue tipado entero aunque solo venga
metaTitle. Pide select: ['seo'] si prefieres que el tipo y el valor coincidan.
Leer listas: array y blocks
Sección titulada «Leer listas: array y blocks»Una lista llega siempre en el documento, como un array de filas: []
si no tiene ninguna, nunca null. Cada fila trae su id, y las de un blocks también su blockType.
parent y _order, que son de la tabla hija, no salen nunca.
const post = await cms.collections.posts.findByID(id)
post.links // [{ id: '01930d4c-…', label: 'Docs', url: '/docs' }, …]post.sections // [{ id: '01930d4d-…', blockType: 'hero', title: 'Hola', image: 'm1' }, …]Las filas salen en el orden en que se escribieron (_order, y el id como desempate, así que dos lecturas
seguidas no las intercambian) y con los mismos id. Sus subcampos se leen como los de primer nivel: un date
es un Date, un checkbox un booleano, un json el valor y no su texto. El tipo generado
(Post['links']) es exactamente lo que esta lectura devuelve con depth: 0.
select decide qué listas se leen. El nombre de la lista la trae entera; un subcampo, no:
find({ select: ['title'] }) // sin listas: ni se consultanfind({ select: ['title', 'links'] }) // links entera, y sections nofind({ select: ['links.label'] }) // QueryErrorLo mismo para where y sort: where: { 'links.label': … } y sort: 'links' son un QueryError (un 400
por REST). Todos dicen la misma frase: una lista no se filtra, ordena ni proyecta por subcampo: se lee entera,
con select: ['links'] o sin select. Filtrar y ordenar por las filas llega más adelante.
Un global lee sus listas igual, desde su clave de KV: mismas filas, mismos
id (la posición, en las guardadas antes de tenerlo) y mismo select.
Las filas heredan el acceso del documento. Lo que el access.read de la colección deja fuera —un Where o
un «nada»— no trae filas, porque no trae documento. Si una lista declara su propio access.read y el actor no
lo cumple, la lista no sale, como cualquier campo. El afterRead de la lista y el de la colección ven la lista
entera, con las relaciones de sus filas ya resueltas si hay depth.
Cuesta una sentencia por tabla hija, no por fila
Sección titulada «Cuesta una sentencia por tabla hija, no por fila»Las tablas hijas se leen en el mismo batch() que el documento: con T tablas hijas (un array es una; un
blocks, una por cada tipo de bloque), find cuesta T + 2 sentencias —las filas, el COUNT(*) y las
tablas hijas—, y findOne y findByID cuestan T + 1, en un solo viaje a D1. No dependen de cuántas filas
tenga una lista ni de cuántos documentos haya en la página. Una colección sin listas, o un select que no
nombra ninguna, siguen costando lo que costaban.
Lo que sí crece con T es el trabajo de la base: cada sentencia vuelve a evaluar el where y el orden de la
página para saber de qué documentos son las filas. Si no vas a pintar una lista, no la pidas en el select.
Varios valores: hasMany
Sección titulada «Varios valores: hasMany»Un campo con hasMany: true llega siempre en el
documento como un array de valores, en el orden en que se escribieron: [] si no tiene ninguno, nunca null.
Los valores salen sueltos, sin id ni _order.
const post = await cms.collections.posts.findByID(id)
post.tags // ['tech', 'news']post.scores // [3, 1, 2] el orden de escritura, no el numéricopost.keywords // [] si nunca se escribió o se vacióselect decide qué campos se leen, y el nombre de un hasMany lo trae entero (select: ['title', 'tags']); sin
select vienen todos. sort por un hasMany es un QueryError (un 400 por REST): un documento no tiene un
único valor por el que ordenarlo. depth hidrata las relaciones y el hasMany de cada documento hidratado llega
también. Los hasMany de relationship y upload tienen su propia sección.
Filtrar por sus valores
Sección titulada «Filtrar por sus valores»Cada condición sobre un hasMany pregunta por cualquiera de sus valores:
| Operador | Se cumple cuando… |
|---|---|
equals, in, like, contains, greater_than… |
algún valor cumple la condición |
not_equals, not_in |
ningún valor cumple equals / in: es el complemento, y un documento sin valores pasa |
exists: true |
tiene al menos un valor |
exists: false |
no tiene ninguno: [] y «nunca se escribió» son lo mismo |
await cms.collections.posts.find({ where: { tags: { in: ['news', 'tech'] } } }) // alguna es news o techawait cms.collections.posts.find({ where: { tags: { not_equals: 'news' } } }) // ninguna es newsawait cms.collections.posts.find({ where: { scores: { greater_than: 5 } } }) // alguna puntuación supera 5Por REST, igual:
GET /api/cms/posts?where[tags][equals]=newsGET /api/cms/posts?where[tags][in][0]=news&where[tags][in][1]=techGET /api/cms/posts?where[tags][exists]=falseequalsynot_equalsdel mismo valor reparten la colección en dos: ni un documento en los dos ni uno en ninguno. Eso es lo que hace denot_equals«ninguno es…» y no «alguno no es…», y por eso un post con las etiquetasnewsytechno sale connot_equals: 'tech'.- Cada condición tiene su propia comprobación. Para pedir dos valores a la vez, dos condiciones:
and: [{ tags: { equals: 'news' } }, { tags: { equals: 'tech' } }]. Un operador no puede pedir dos valores. equalscon una lista es unQueryError, nunca «igual a alguno»: para eso estáin. Por REST, repetirwhere[tags][equals]=a&where[tags][equals]=bllega como una lista y es un400.- Un número llega como texto por REST y se compara como número, igual que en un campo de siempre.
- El
wherede lectura puede nombrarlos, el de escritura no. Unaccess.readque devuelve{ tags: { equals: 'news' } }filtra las lecturas. Uno deaccess.updateo deaccess.deletecon unhasManyse rechaza con unAccessError(un500por REST, con el motivo en el registro del Worker), porque esa condición se vuelve a comprobar después de que la escritura reemplace los valores que lee. Ver Limitaciones. - No añade sentencias, pero tampoco hay índice sobre el valor: cada condición recorre los valores de los
documentos candidatos. Con muchos documentos y un filtro frecuente por un valor, valora un campo normal con
index.
Relaciones y ficheros: hasMany
Sección titulada «Relaciones y ficheros: hasMany»Un hasMany de relationship o upload llega en el
documento como un array, en el orden en que se escribió y nunca null: ids con depth: 0, documentos con depth: 1.
Con una colección en to es una lista de ids; con varias, de pares { relationTo, value }.
const post = await cms.collections.posts.findByID(id, { depth: 0 })
post.categories // ['c1', 'c2']post.related // [{ relationTo: 'pages', value: 'p1' }, { relationTo: 'categories', value: 'c3' }]
const hydrated = await cms.collections.posts.findByID(id, { depth: 1 })
hydrated.related[0].value // el documento de la página p1, con su colección en relationTodepth los hidrata por lote y por nivel, como cualquier relación: una consulta por colección destino y nivel,
con los ids repartidos de 100 en 100 (D1 admite 100 variables por sentencia), no una por documento ni por elemento. Un
find de 50 posts con tres campos de este tipo cuesta las mismas consultas que uno de 5.
- Cada destino se vuelve a autorizar. Un elemento hacia una colección que quien llama no puede leer se queda como
el id (en un polimórfico, como
{ relationTo, value: 'p1' });publicOnlyhace lo mismo con las cerradas. - La carpeta reservada de
ssdno se hidrata: un fichero de.systemen una galería sale con su id. - Un id que ya no resuelve se queda como el id. Nunca rompe la lectura.
- Los destinos traen sus propias listas. Lo que
depth: 1trae de una colección con unhasManylo trae como ids (una consulta por tabla hija); condepth: 2esas listas se resuelven en la ronda siguiente. - La lectura ordena por
_ordery no supone que sea contiguo: tras borrar un destino cononDelete: 'setNull'la lista conserva el orden de los que quedan.
Filtrar por sus elementos
Sección titulada «Filtrar por sus elementos»Cada condición pregunta por cualquiera de los elementos, con las mismas reglas de los valores sueltos
(not_equals y not_in son el complemento, exists: false es la lista vacía):
await cms.collections.posts.find({ where: { categories: { equals: 'c1' } } }) // alguna es c1await cms.collections.posts.find({ where: { gallery: { in: ['m1', 'm2'] } } }) // alguna foto es m1 o m2await cms.collections.posts.find({ where: { categories: { exists: false } } }) // ningunaCon varias colecciones, un id solo no dice de cuál es: el campo se filtra por la colección.
Clave del where |
Pregunta |
|---|---|
related.pages |
algún elemento es de pages y su id cumple la condición (equals, in, not_equals, not_in, exists) |
related.relationTo |
de qué colección es algún elemento: equals, in, not_equals, not_in con el nombre de la colección |
related |
solo exists: si tiene algún elemento. Con otro operador es un QueryError que dice cómo filtrar |
await cms.collections.posts.find({ where: { 'related.pages': { equals: 'p1' } } })await cms.collections.posts.find({ where: { 'related.relationTo': { in: ['pages'] } } })Por REST: GET /api/cms/posts?where[related.pages][equals]=p1.
Reglas que no cambian: sort por un hasMany es un QueryError; el where de un access.update o access.delete que
nombre uno se rechaza con un AccessError; filtrar no añade sentencias, y sí hay un índice (una columna por
colección destino), así que equals e in sobre el id no recorren la tabla. Una fila con todas las columnas a NULL
no es un elemento y exists no la cuenta.
Relaciones: depth
Sección titulada «Relaciones: depth»depth |
Qué devuelve un campo relationship o upload |
|---|---|
0 |
El id: '01930d4c-…' |
1 |
El documento entero, con sus propias relaciones en ids |
n |
Se repite hasta n niveles (máximo 10) |
Por defecto es 1, que es lo que casi siempre quieres al pintar una plantilla. Un campo upload se resuelve
igual que un relationship.
depth re-autoriza cada destino: una relación solo se resuelve si quien llama puede leer la
colección a la que apunta. Si no puede, se queda el id, como si el documento no existiera. Una llamada
anónima, que es la de por defecto, hidrata hacia las colecciones con read: 'public' —la biblioteca
ssd lo es— y no hacia users: para que author llegue resuelto en una página que decide qué mostrar,
la llamada lleva overrideAccess: true.
Por eso el tipo generado es una unión y no solo el id:
interface Post { cover: string | Medio | null}Con depth decidido en tiempo de ejecución, TypeScript no puede saber qué rama toca, así que lo dice.
Estrechas al usarlo:
---const ssd = Astro.locals.cms.collections.ssd---
{typeof post.cover === 'object' && post.cover !== null && ( <img src={ssd.url(post.cover)} alt={post.cover.alt ?? ''} />)}El documento resuelto trae sus campos —filename, mimeType, alt…— pero no una url: la ruta la
construye url(), que vive en la colección upload. Ver Ficheros.
Un id que no resuelve se queda como la cadena que era. La fila puede haberse borrado entre dos consultas, o alguien puede haber escrito en D1 por fuera. Ni se pierde el id —que es la única pista para saber de dónde venía— ni se cae un listado de cincuenta artículos por una referencia rota.
Cuesta consultas fijas, no una por documento
Sección titulada «Cuesta consultas fijas, no una por documento»Por cada nivel se agrupan todos los ids que apuntan a la misma colección, se deduplican y se lanza una sola consulta por colección de destino. Cincuenta artículos con autor y portada son tres consultas, no cincuenta y una.
depth también entra en las filas. Un relationship o un upload dentro de una fila de una lista se resuelve con
las mismas reglas que uno de primer nivel —re-autoriza el destino, y lo que el actor no puede leer se queda como
id—, y los documentos que trae consigo sus listas: post.author.links existe con depth: 1. Las filas de lo
hidratado se leen con una sentencia por tabla hija y nivel, en un solo batch(), sea cual sea el número de
documentos. Cincuenta artículos con autor y portada, y una lista de enlaces con un relationship en cada fila, siguen
siendo consultas fijas.
Un upload roto dentro de una fila no tumba la lectura, igual que en primer nivel. Si borras el medio, la celda
de la fila queda en null (la clave foránea es ON DELETE SET NULL) y se lee null. Si el id no resuelve —un medio de
una carpeta reservada, un destino cerrado, una fila escrita por fuera— se queda el id.
Escribir
Sección titulada «Escribir»Escribir exige sesión, y una llamada sin quién la hace es anónima. En los ejemplos de esta sección escribe
el servidor —un seed, un endpoint tuyo que decide—, así que cada llamada lleva overrideAccess: true.
Si escribe una persona y debe valer lo que ella puede, en su lugar va { user }, o la API envuelta con
forUser.
const post = await cms.collections.posts.create( { title: 'Hola', slug: 'hola', status: 'published', cover: 'a1b2c3d4-…', // en escritura, una relación es siempre el id }, { overrideAccess: true },)create valida contra el esquema de la colección, aplica los defaultValue a lo que falte, genera id,
createdAt y updatedAt, inserta y devuelve el documento con sus relaciones ya resueltas y pasado por el
afterRead de la colección, si declara alguno: lo devuelto es lo que daría una lectura, no la fila
cruda. Lo que se guarda no cambia (ver Hooks).
El id lo genera siempre el CMS, un UUID v7. Pasarlo a mano se rechaza, igual que createdAt y
updatedAt. Es lo que hace que todos los ids sean ordenables por tiempo por construcción: los 48 bits altos
de un v7 son el timestamp en milisegundos, así que el índice de la clave primaria sirve además de índice de
orden de creación.
update es parcial. Lo que no mandes se queda como estaba, y updatedAt se refresca siempre:
await cms.collections.posts.update(post.id, { title: 'Hola de nuevo' }, { overrideAccess: true })Con un group la parcialidad baja un nivel: update(id, { seo: { metaTitle: 'A' } })
cambia ese subcampo y conserva los hermanos, y { seo: null } los pone todos a null. Un
point se escribe de una pieza, [lng, lat], o null.
Si lo que escribes sale de una lectura anterior —un formulario, una integración que lee y reescribe— puedes
pedir que la escritura aplique solo si nadie tocó el documento entre medias, pasando el updatedAt que
leíste en ifMatch. Si ya no coincide, no se escribe nada y salta PreconditionFailedError; relee y
reintenta. Es opcional, y la API REST lo expone como
If-Match:
await cms.collections.posts.update( post.id, { title: 'Hola de nuevo' }, { ifMatch: post.updatedAt.toISOString(), overrideAccess: true },)delete devuelve el documento borrado, para que puedas registrar qué desapareció —o deshacerlo— sin una
lectura previa. Como las demás escrituras, acepta { user, overrideAccess } como segundo argumento:
await cms.collections.posts.delete(post.id, { overrideAccess: true })Listas: array y blocks
Sección titulada «Listas: array y blocks»Una lista de filas (array y blocks) se escribe por reemplazo: la
lista que mandas es la que queda.
const post = await cms.collections.posts.create( { title: 'Hola', slug: 'hola', status: 'published', links: [{ label: 'Inicio', url: '/' }, { label: 'Blog', url: '/blog' }], sections: [{ blockType: 'hero', title: 'Bienvenida' }], }, { overrideAccess: true },)// post.links[0].id → 'a1b2…': un UUID v7 por fila, acuñado por el servidor
await cms.collections.posts.update( post.id, { links: [post.links[1], { label: 'Contacto', url: '/contacto' }] }, { overrideAccess: true },)// links: la fila 'Blog' (con su id) y la nueva, en ese orden. 'Inicio' desaparece.updatesigue siendo parcial por campo: una lista que no mandas no se toca,links: []la vacía ylinks: nulles un400(INVALID_TYPE). No hay parches por fila: se manda la lista entera.create,updateydeletedevuelven el documento con sus listas, y los hooks (beforeChange,afterChange,originalDoc,previousDoc) las ven enteras.- Las filas con
idlo conservan y las demás reciben un UUID v7. Elides único dentro del documento, no entre documentos. - El documento y todas sus filas se escriben en un solo
batch()de D1, con las mismas sentencias para 10 filas que para 1000; si una falla, no se escribe nada. Un404o un412no tocan ninguna tabla hija.
Escribir varios valores: hasMany
Sección titulada «Escribir varios valores: hasMany»Un campo con hasMany se escribe por reemplazo, como
una lista de filas: el array que mandas es el que queda.
const post = await cms.collections.posts.create( { title: 'Hola', slug: 'hola', status: 'draft', tags: ['news', 'tech'], scores: [3, 1, 2] }, { overrideAccess: true },)
await cms.collections.posts.update(post.id, { tags: ['life'] }, { overrideAccess: true })// tags queda ['life']; scores no se toca- Ausente no toca;
[]vacía;nulles un400(INVALID_TYPEsobre el campo). Vaciar un campo estags: [], y unrequiredlo rechaza (REQUIRED). - El orden y los duplicados se conservan:
['b', 'a', 'b']se guarda y se lee tal cual. Un valor falso (0,'') es un valor como cualquier otro. - Cada valor se valida con su ruta:
tags.1es el segundo (INVALID_OPTIONsi no está en las opciones delselect,NOT_INTEGER,MAX_LENGTH…), y la lista entera puede darREQUIRED,MIN_ROWSoMAX_ROWS. - Se guarda en el mismo
batch()que el documento, con una sentencia por tabla hija: las mismas sentencias para 3 valores que para 100. Si una falla, no se escribe nada; un404o un412no tocan los valores; ydeletelos borra con el documento. - No hay «añadir un valor». Para cambiar uno se lee el array y se manda entero. Sin
ifMatch, dos guardados a la vez del mismo campo son last-write-wins sobre toda la lista de valores, como en una lista de filas. - Los hooks (
beforeValidate,beforeChange,afterChange,afterRead, los del campo incluidos) ven y pueden devolver el array; lo que devuelven se vuelve a validar.
Escribir relaciones y ficheros: hasMany
Sección titulada «Escribir relaciones y ficheros: hasMany»Igual que los demás: por reemplazo, con ids (o con { relationTo, value } en un polimórfico).
await cms.collections.posts.update( post.id, { categories: ['c3', 'c1'], related: [{ relationTo: 'pages', value: 'p1' }], gallery: [] }, { overrideAccess: true },)- Cada elemento se valida con su ruta. Un id que no existe es
INVALID_RELATIONencategories.1, con el nombre de la colección; un fichero que elacceptdel campo no admite,INVALID_FILE_TYPEengallery.1; una colección que el campo no admite,INVALID_OPTIONenrelated.0.relationTo. Salen todos juntos. - El camino que funciona no paga la comprobación de existencia: la clave foránea la hace en el mismo
batch(), y solo si falla se hace una consulta (por colección destino, de 100 ids en 100) para decir qué elementos faltaban. - Todo o nada: el documento y todas sus listas van en un solo
batch(). Si un elemento falla, ni el padre ni ninguna lista cambia. Y un destino que se borra entre la validación y la escritura es el mismoINVALID_RELATION, no un500. - Borrar un documento borra las filas de sus listas. Borrar un destino depende de
onDelete:'setNull'quita el elemento de la lista;'restrict'no deja borrarlo (RESTRICTED, con el nombre del documento y del campo).
Errores
Sección titulada «Errores»Todos heredan de CMSError y llevan un code estable y un status. El mensaje es para humanos y puede
cambiar; el code no.
| Clase | code |
status |
Cuándo |
|---|---|---|---|
ValidationError |
VALIDATION_ERROR |
400 | El documento no pasa el esquema, o choca un constraint |
QueryError |
QUERY_ERROR |
400 | where, sort, select, limit, page o depth mal formados |
UnauthorizedError |
UNAUTHORIZED |
401 | No hay sesión y access no deja pasar: lo que pasa con una llamada anónima, que es la de por defecto |
ForbiddenError |
FORBIDDEN |
403 | Hay sesión y la función de access dice que no |
NotFoundError |
NOT_FOUND |
404 | El documento no existe, o una condición de access lo deja fuera: el mismo error y el mismo texto |
PreconditionFailedError |
PRECONDITION_FAILED |
412 | El ifMatch de update ya no coincide con el updatedAt |
DatabaseError |
DATABASE_ERROR |
500 | D1 ha fallado; el error original va en cause |
ValidationError trae un issues con un problema por campo, que es lo que el administrador pinta debajo de
cada uno:
try { await cms.collections.posts.create( { title: 'Repetido', slug: 'hola', status: 'draft' }, { overrideAccess: true }, )} catch (error) { if (error instanceof ValidationError) { console.log(error.issues) // [{ path: 'slug', code: 'UNIQUE', message: 'Ya existe un documento con ese slug' }] }}Un slug duplicado o una relación que apunta a un documento inexistente son errores de quien escribe, no del
servidor, así que salen como 400 con el campo culpable señalado y no como un fallo interno:
| Lo que falla | code del issue |
|---|---|
Un unique que ya existe |
UNIQUE |
| Una relación a un id que no existe | INVALID_RELATION (si está dentro de una fila, sobre la lista: links) |
Borrar algo a lo que otros apuntan con onDelete: 'restrict' |
RESTRICTED |
Lo que no encaje con ninguno de esos patrones cae a DatabaseError 500 sin inventar nada: un error mal
traducido es peor que uno genérico.