Leia e escreva dados com GraphQL no Fabric Apps

O Fabric Apps fornece um cliente GraphQL seguro para tipos que permite realizar operações de criação, leitura, atualização e eliminação sem escrever consultas brutas. O cliente gera automaticamente GraphQL a partir das chamadas de método e devolve entidades tipadas com base nas definições do seu modelo de dados.

Pré-requisitos

• Um projeto de Fabric Apps com modelos de dados definidos. Veja Definir modelos de dados.
• Os serviços de backend a correr localmente ou implementados no Fabric.

Inicializar o cliente

Instancie RayfinClient com o URL do seu backend, a sua chave publicável e o tipo de esquema:

import { RayfinClient } from '@microsoft/rayfin-client';
import type { Note } from '../rayfin/data/Note';
import type { Notebook } from '../rayfin/data/Notebook';

type AppSchema = { 
  Note: Note;
  Notebook: Notebook;
};

const client = new RayfinClient<AppSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: 'pk-your-project-key',
});

O argumento genérico de tipo permite que o TypeScript forneça autocompletamento e verificação de tipos para todas as operações de dados.

Ler dados

Aceda a coleções de entidades através de client.data.<EntityName>. A API fluent fornece métodos para consulta, filtragem, ordenação e paginação.

Buscar todos os registos

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

Buscar um único registo pela chave primária

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

Devolve a entidade completa ou null se não existir nenhum registo com esse ID.

Filtrar registos

Use o where() método para filtrar resultados:

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

Operadores de filtro

Ordenar os resultados

Use orderBy() para ordenar resultados de consultas:

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

Ordene por várias colunas:

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

Navegar nas relações

Quando define relações com @one() e @many() decoradores, pode incluir campos de entidades relacionadas na mesma consulta:

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

Cada nota inclui os dados associados do caderno sem necessidade de uma consulta separada.

Paginar grandes conjuntos de resultados

Use paginação baseada em cursor para listas grandes:

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

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

Obtém a página seguinte usando o cursor:

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

Criar registos

Use o create() método para inserir novos registos:

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',
});

O método devolve a entidade criada com todos os campos preenchidos, incluindo o gerado idautomaticamente .

Crie registos com relações

Ao criar entidades que tenham relações, passe ou o objeto relacionado completo ou um objeto com apenas a chave primária:

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

// Option 2: Pass the full object
const notebook = await client.data.Notebook.findByPk('notebook-456');
const note = await client.data.Note.create({
  title: 'Weekly summary',
  content: 'Summary of this week',
  notebook: notebook,
  isPinned: false,
  isArchived: false,
  createdAt: new Date(),
  updatedAt: new Date(),
});

Ambas as formas produzem o mesmo resultado. Use o primeiro formulário quando já souber o ID da entidade relacionada e quiser evitar uma busca extra.

Atualizar registos

Use o update() método para modificar registos existentes. Forneça um objeto de filtro e um objeto que contenha os campos a atualizar:

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

Atualizar relações

Para alterar uma relação, passe a nova entidade relacionada ou apenas o seu ID:

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

Excluir registros

Use o delete() método para remover registos que correspondam a um filtro:

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

O método resolve-se quando o backend confirma a eliminação. Se nenhum registo corresponder ao filtro, o método ainda assim tem sucesso.

Gerir autenticação

Quando a autenticação estiver ativada, inicie sessão antes de realizar operações de dados:

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

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

O cliente anexa automaticamente a sessão de autenticação a todas as chamadas API de dados. Não precisas de passar os tokens manualmente.

Melhores práticas

• Selecione apenas os campos necessários – Busque apenas os campos que usa para reduzir o tamanho da carga útil e melhorar o desempenho.
• Use paginação para listas grandes – Evite obter milhares de registos de uma só vez usando first() e executePaginated().
• Consultas de relacionamento por lote – Inclua campos de entidade relacionada na mesma consulta em vez de fazer pedidos separados.
• Cache de dados frequentemente acedidos – Armazene dados de referência estática na memória para reduzir chamadas de API.

Limitações atuais

• O método count() não está disponível no cliente Fluent. Selecione campos mínimos e use results.length em vez disso.
• Relações muitos-para-muitos não são suportadas. Use uma entidade de junção explícita com dois @one() decoradores de navegação.
• A propriedade totalCount em PagedResult não é preenchida pelo backend.

Conteúdo relacionado

• Definir modelos de dados
• Configurar a autenticação
• Implementar no Fabric