Model.findMany
Importe uma interface @model exportada e chame Model.findMany(filter) para buscar seus registros. O método retorna Promise<Result<Model[], DbError>> e aplica os mapeamentos físicos de tabela e coluna do modelo.
Aguarde o método antes de usar o Result. Os campos de um filtro plano são combinados com AND. Um valor escalar significa igualdade, como em User.findMany({ active: true }). Para comparações, use um objeto aninhado com um ou mais operadores entre eq, ne, gt, gte, lt e lte, por exemplo User.findMany({ age: { gte: 18 } }).
Os operadores de comparação significam: eq é igual a, ne é diferente de, gt é maior que, gte é maior ou igual a, lt é menor que e lte é menor ou igual a. Quando um campo tem mais de um operador, todas as condições precisam corresponder.
Use or com um array não vazio de objetos de filtro para corresponder a qualquer alternativa. Os campos de cada objeto são combinados com AND, os objetos são combinados com OR, e os campos ao lado de or continuam combinados com o grupo inteiro por AND.
Use in com um array não vazio para corresponder a qualquer valor listado. Em um padrão like, % corresponde a zero ou mais caracteres e _ corresponde a um caractere: "Ada" corresponde exatamente a Ada, "Ada%" corresponde a valores que começam com Ada, "%son" corresponde a valores que terminam com son e "%Ada%" corresponde a valores que contêm Ada em qualquer posição. A correspondência segue o comportamento LIKE do backend configurado. Todos os valores continuam sendo parâmetros e são verificados em relação à coluna do modelo selecionado.
Este exemplo pressupõe que o modelo declare os campos active, age e role.
import { DbError } from "tyrus:db";
import { User } from "./models/User";
async function findAdministrators(): Promise<Result<User[], DbError>> {
const data = await User.findMany({
active: true,
role: { like: "admin%" },
or: [
{ age: { gte: 18 } },
{ id: { in: [1, 2, 3] } }
]
}) onfail {
return Err(data);
};
return Ok(data);
}Carregamento de relações
Declare relações de modelo com @belongsTo("foreignKeyField"), @hasOne("foreignKeyField"), @hasMany("foreignKeyField") ou @manyToMany("pivotTable", "sourceKey", "targetKey") e passe seus nomes em { include: ["team"] }. Selecione um subconjunto de campos escalares com { include: [{ team: ["id", "name"] }] }; o tipo do resultado reflete os campos selecionados. Includes sem projeção retornam o Model relacionado completo. O carregamento é explícito, usa uma instrução SQL e aceita somente um nível. Incluir uma relação hasMany ou manyToMany exige relationLimit de 1 a 500, que limita cada coleção incluída. Coleções relacionadas são ordenadas pelo @id do Model relacionado para manter resultados estáveis.
import { DbError } from "tyrus:db";
@model("teams")
export interface Team {
@id
id: i64;
name: string;
}
@model("roles")
export interface Role {
@id
id: i64;
name: string;
}
@model("users")
export interface User {
@id
id: i64;
@foreignKey("teams", "id")
teamId: i64?;
@belongsTo("teamId")
team: Team?;
@manyToMany("user_roles", "user_id", "role_id")
roles: Role[]?;
}
async function listUsers(): Promise<Result<User[], DbError>> {
const result = await User.findMany({}, { include: ["team"] });
return result;
}
interface UserRoleNames {
id: i64;
teamId: i64?;
team: Team?;
roles: { name: string }[]?;
}
async function listUserRoleNames(): Promise<Result<UserRoleNames[], DbError>> {
const data = await User.findMany({}, {
include: [{ roles: ["name"] }],
relationLimit: 100
}) onfail {
return Err(data);
};
return Ok(data);
}Paginação numerada
Passe { paginate: true, pageSize, page? } como segundo argumento para retornar uma página numerada. A página padrão é 1. Page<T> contém items, total, pageSize, page e totalPages; total conta todos os registros correspondentes ao filtro antes da paginação. O MongoDB oferece paginação numerada ordenando por _id e aplicando o deslocamento solicitado. Importe Page de tyrus:db quando citar esse resultado na assinatura de uma função.
import { DbError, Page } from "tyrus:db";
import { User } from "./models/User";
async function listUsersPage(): Promise<Result<Page<User>, DbError>> {
const data = await User.findMany({}, { paginate: true, pageSize: 25, page: 1 }) onfail {
return Err(data);
};
return Ok(data);
}Cursor pagination uses the same Page<T> result type. nextCursor contains the serialized @id value of the last returned row, not an item count or page number; omit after for the first page and pass nextCursor back unchanged to continue. total still counts every record matching the filter, before the cursor position.
import { DbError, Page } from "tyrus:db";
import { User } from "./models/User";
async function listNextUsers(after: string): Promise<Result<Page<User>, DbError>> {
const data = await User.findMany({}, { paginate: true, pageSize: 25, cursor: true, after }) onfail {
return Err(data);
};
return Ok(data);
}Paginação por cursor
Defina cursor: true para usar paginação por cursor. Omita after na primeira chamada; na próxima, passe o nextCursor da página anterior sem alterações. O cursor é o valor serializado do @id da última linha retornada, não a quantidade de itens nem o número da página. Para um @id inteiro, after: "10" continua após o id 10, não no décimo resultado. Os resultados são ordenados pelo @id do modelo, e hasMore indica se existe outra página. total continua contando todos os registros correspondentes, independentemente da posição do cursor. O MongoDB usa o _id gerado para ordenar e comparar o cursor, cujo token é o valor serializado de ObjectId de 24 caracteres retornado na página.
O compilador verifica cada campo em relação ao modelo e valida a consulta gerada e os tipos dos parâmetros contra o snapshot local do schema do backend relacional configurado. O MongoDB usa a mesma API de filtros do modelo, mas não usa snapshot de schema relacional. A contagem e os itens da página são lidos separadamente, então gravações concorrentes podem alterar o total observado entre chamadas de página. Os valores são vinculados por placeholders; os identificadores de tabela e coluna vêm apenas da declaração do modelo.
As mutações do modelo estão documentadas na página Modelos. Use findOne para retornar um registro ou um valor de ausência tipado.
