Leer y escribir datos con GraphQL en Fabric Apps

Fabric Apps proporciona un cliente GraphQL con seguridad de tipos que permite realizar operaciones de creación, lectura, actualización y eliminación sin tener que escribir consultas directamente. El cliente genera GraphQL automáticamente a partir de las llamadas a tus métodos y devuelve entidades tipadas según las definiciones de tu modelo de datos.

Prerequisites

  • Un proyecto de Fabric Apps con modelos de datos definidos. Consulte Definición de modelos de datos.
  • Los servicios back-end que se ejecutan localmente o se implementan en Fabric.

Inicialización del cliente

Cree RayfinClient una instancia con la dirección URL de back-end, la clave que se puede publicar y el tipo de esquema:

import { RayfinClient } from '@microsoft/rayfin-client';
import type { UniversalAppSchema } from '@rayfin-app/shared';

const client = new RayfinClient<UniversalAppSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

El argumento de tipo genérico permite a TypeScript ofrecer autocompletado y verificación de tipos en todas las operaciones de datos.

Estos ejemplos suponen que activaste los datos y registraste Note y Notebook en el contrato de esquema compartido y packages/data/src/index.ts de la aplicación universal. En una plantilla plana, importa tu tipo de esquema desde rayfin/data/schema.ts en su lugar. Consulte Definición de modelos de datos.

Lectura de datos

Acceda a colecciones de entidades a través de client.data.<EntityName>. La API fluida proporciona métodos para consultar, filtrar, ordenar y paginar.

Consigue una página de registros

execute() solo devuelve una página, con 100 registros por defecto. No devuelve los metadatos del cursor ni recupera páginas posteriores. Utiliza la paginación hacia delante para listas que puedan crecer más allá de una página.

const notes = await client.data.Note.select([
  'id',
  'title',
  'content',
  'createdAt',
  'isPinned',
]).execute();

Captura de un único registro por clave principal

const note = await client.data.Note.findById('00000000-0000-0000-0000-000000000000');

findById() devuelve null si no existe ningún registro. La implementación publicada selecciona solo la clave primaria, así que no asumas que los demás campos de la entidad estén poblados. Selecciona campos explícitamente cuando necesites sus valores:

const notes = await client.data.Note.select(['id', 'title', 'content'])
  .where({ id: { eq: '00000000-0000-0000-0000-000000000000' } })
  .first(1)
  .execute();

const note = notes[0] ?? null;

Filtrar registros

Use el where() método para filtrar los resultados:

const pinnedNotes = await client.data.Note.select([
  'id',
  'title',
  'isPinned',
])
  .where({ isPinned: { eq: true } })
  .execute();

Operadores de filtro

Operador Descripción Ejemplo
eq Es igual { status: { eq: 'active' } }
neq No es igual { status: { neq: 'archived' } }
gt Mayor que { age: { gt: 18 } }
gte Mayor o igual que { age: { gte: 21 } }
lt Menor que { price: { lt: 100 } }
lte Menor o igual que { price: { lte: 50 } }
contains Contiene subcadena { title: { contains: 'draft' } }

Ordenar resultados

Use orderBy() para ordenar los resultados de la consulta:

const notes = await client.data.Note.select([
  'id',
  'title',
  'createdAt',
])
  .orderBy({ createdAt: 'desc' })
  .execute();

Ordenar por varias columnas:

const notes = await client.data.Note.select([
  'id',
  'title',
  'isPinned',
  'createdAt',
])
  .orderBy({ isPinned: 'desc' })
  .orderBy({ createdAt: 'desc' })
  .execute();

Al definir relaciones con @one() y @many() decoradores, puede incluir campos de entidad relacionados en la misma consulta:

const notes = await client.data.Note.select([
  'id',
  'title',
  'content',
  'notebook.id',
  'notebook.name',
])
  .execute();

Cada nota incluye sus datos de cuaderno asociados sin necesidad de una consulta independiente.

Paginar grandes conjuntos de resultados

Use la paginación basada en cursores para listas grandes:

const page = await client.data.Note.select([
  'id',
  'title',
  'createdAt',
])
  .orderBy({ createdAt: 'desc' })
  .orderBy({ id: 'asc' })
  .first(25)
  .executePaginated();

console.log('Items:', page.items);
console.log('Has next page:', page.hasNextPage);
console.log('End cursor:', page.endCursor);

Capture la página siguiente con el cursor:

if (page.hasNextPage) {
  if (!page.endCursor) {
    throw new Error('The next page is missing its cursor.');
  }
  const nextPage = await client.data.Note.select([
    'id',
    'title',
    'createdAt',
  ])
    .orderBy({ createdAt: 'desc' })
    .orderBy({ id: 'asc' })
    .first(25)
    .after(page.endCursor)
    .executePaginated();
}

Note

El backend no rellena la propiedad totalCount del tipo PagedResult. El page.items.length valor solo cuenta la página actual, no todos los registros coincidentes.

Para procesar cada registro coincidente, continúa adelante hasta que hasNextPage sea false. Mantén las selecciones, filtros y orden de clasificación sin cambios entre solicitudes.

let cursor: string | undefined;
let matchingRecords = 0;

while (true) {
  let query = client.data.Note.select(['id'])
    .where({ isArchived: { eq: false } })
    .orderBy({ id: 'asc' })
    .first(100);

  if (cursor !== undefined) {
    query = query.after(cursor);
  }

  const page = await query.executePaginated();
  matchingRecords += page.items.length;

  if (!page.hasNextPage) {
    break;
  }
  if (!page.endCursor) {
    throw new Error('The next page is missing its cursor.');
  }
  cursor = page.endCursor;
}

console.log('Records read across all pages:', matchingRecords);

La paginación no proporciona una instantánea entre solicitudes. Los cambios simultáneos pueden afectar los registros que lees y cuentas.

Agregar y agrupar datos

Use aggregate() para totales del lado del servidor y groupBy() para resúmenes por grupo. El método fluido count() independiente no está disponible, pero count está soportado dentro de una especificación de agregación.

Las cinco operaciones agregadas (sum, avg, min, max, y count) requieren un campo numérico. No cuentes un UUID id ni un campo de texto. Por ejemplo, la siguiente consulta supone una entidad registrada Product con un campo numérico stockQuantity requerido:

const totals = await client.data.Product.where({ isAvailable: { eq: true } })
  .aggregate({
    matchingProducts: { count: 'stockQuantity' },
    totalStock: { sum: 'stockQuantity' },
    averageStock: { avg: 'stockQuantity' },
    lowestStock: { min: 'stockQuantity' },
    highestStock: { max: 'stockQuantity' },
  })
  .execute();

console.log(totals[0].aggregations.matchingProducts);

count cuenta los valores no nulos del campo numérico especificado. Utiliza un campo numérico requerido para contar las filas que coinciden. Si tu entidad no tiene un campo adecuado, cuenta los identificadores en todas las páginas como se mostró antes, no solo en una página.

Para totales agrupados:

const groups = await client.data.Product.groupBy(['status'])
  .aggregate({
    matchingProducts: { count: 'stockQuantity' },
    totalStock: { sum: 'stockQuantity' },
  })
  .execute();

for (const row of groups) {
  console.log(row.fields.status, row.aggregations.totalStock);
}

Los resultados de agregación son arrays con fields y aggregations objetos. Un total general tiene una fila con un objeto vacío fields . count devuelve un number; las demás operaciones devuelven number | null para entradas vacías o totalmente nulas.

Aplica where() antes de la agregación. No combines la agregación con selección de filas, ordenación ni paginación a través de select(), orderBy(), first(), o after().

Crear registros

Use el create() método para insertar nuevos registros:

const newNote = await client.data.Note.create({
  title: 'Meeting notes',
  content: 'Discussion points from the team sync',
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
  user_id: 'user-123',
});

El método devuelve el registro creado, incluyendo su registro autogenerado id Usa una explicit selected read cuando necesites campos almacenados adicionales.

Creación de registros con relaciones

Al crear entidades que tienen relaciones, pase el objeto relacionado completo o un objeto con solo la clave principal:

// Option 1: Pass just the ID
const note = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  notebook: { id: '22222222-3333-4444-5555-666666666666' },
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

// Option 2: Select the related fields you need before creating the note.
const notebooks = await client.data.Notebook.select(['id', 'name'])
  .where({ id: { eq: '22222222-3333-4444-5555-666666666666' } })
  .first(1)
  .execute();
const notebook = notebooks[0];
if (!notebook) {
  throw new Error('Notebook not found.');
}

const noteWithNotebook = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  notebook,
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

Ambas formas generan el mismo resultado. Use el primer formulario cuando ya conozca el identificador de la entidad relacionada y quiera evitar una captura adicional.

El cliente utiliza la clave primaria del objeto relacionado para establecer la relación. Pasar un objeto no crea ni actualiza el bloc de notas relacionado.

Actualizar registros

Use el update() método para modificar los registros existentes. Pase un objeto de filtro y un objeto que contenga los campos que se van a actualizar:

await client.data.Note.update(
  { id: 'note-123' },
  {
    title: 'Updated title',
    updatedAt: new Date(),
  }
);

Actualización de relaciones

Para cambiar una relación, pase la nueva entidad relacionada o simplemente su identificador:

// Move a note to a different notebook
await client.data.Note.update(
  { id: 'note-123' },
  { notebook: { id: 'new-notebook-789' } }
);

Eliminar registros

Use el delete() método para quitar registros que coincidan con un filtro:

await client.data.Note.delete({ id: 'note-123' });

El método se resuelve cuando el back-end confirma la eliminación. Si no hay registros que coincidan con el filtro, el método sigue funcionando correctamente.

Crea o actualiza un registro

Usa upsert(where, create, update) para crear un registro que falta o actualizar uno existente. Proporciona el mismo ID en la búsqueda y la entrada de creación:

const id = '11111111-2222-3333-4444-555555555555';
const now = new Date();

await client.data.Note.upsert(
  { id },
  {
    id,
    title: 'Daily summary',
    content: 'Summary of today',
    isPinned: false,
    isArchived: false,
    createdAt: now,
    updatedAt: now,
    user_id: 'user-123',
  },
  { title: 'Daily summary', updatedAt: now },
);

Este helper realiza una lectura seguida de una creación o actualización separada. No es atómico, y las llamadas simultáneas pueden producir una condición de carrera. No lo utilices como garantía de transacción o concurrencia.

Gestionar la autenticación

Inicia sesión antes de realizar operaciones con datos protegidos. Para un backend desplegado, utiliza el flujo de inicio de sesión de Microsoft Entra configurado de la app. El siguiente ejemplo de correo electrónico y contraseña es solo para un backend local:

await client.auth.signIn({ email, password });

// All subsequent data calls include authentication context
const notes = await client.data.Note.select(['id', 'title']).execute();

El cliente adjunta automáticamente la sesión de autenticación a todas las llamadas api de datos. No es necesario pasar tokens manualmente.

procedimientos recomendados

  • Seleccionar solo los campos necesarios : capture solo los campos que use para reducir el tamaño de la carga y mejorar el rendimiento.
  • Usar paginación para listas grandes : evite capturar miles de registros a la vez mediante first() y executePaginated().
  • Consultas de relaciones por lotes – Incluya los campos de entidades relacionadas en la misma consulta en lugar de realizar solicitudes separadas.
  • Almacenar datos a los que se accede con frecuencia : almacene datos de referencia estáticos en memoria para reducir las llamadas API.

Limitaciones actuales

  • No existe un método independiente count() . Utiliza una agregación de campo numérico, o cuenta registros en todas las páginas. La longitud de un array solo cuenta los registros devueltos en esa página.
  • No se admiten relaciones de varios a varios. Use una entidad de combinación explícita con dos @one() decoradores de navegación.
  • La propiedad totalCount de PagedResult no la completa el backend.