Linguagem de consulta e busca de dados

Última atualização: 16 de julho de 2026

O PlayServ usa uma sintaxe no estilo LINQ para oferecer destaque e sugestões na IDE. A filtragem de dados é suportada, e as relações aninhadas são expandidas automaticamente conforme o Schema de dados.

---

Buscar um único objeto por chave

Quando você precisa de um objeto específico, use a seleção por chave.

var player = await PlayServ.Model<Player>()
  .Key(playerId)
  .With(p => p.InventoryItems.Price < 500)
  .With(p => p.InventoryItems.Creator.Race == "Gnome");

// sugar
var player = await PlayServ.GetPlayer(playerId);

---

Buscar uma coleção

Para coleções, use Where(...), e use With(...) para blocos aninhados quando necessário.

var players = await PlayServ.Model<Player>()
  .Where(player => player.Age > 15)
  .With(p => p.InventoryItems.Price < 500);

Há uma forma reduzida, com açúcar sintático, para coleções:

var players = await PlayServ.GetPlayers(
  [ p => p.Age > 15 ],
  [ p => p.InventoryItems.Price < 500 ]
);
// C# 12 / .NET 8

---

Where vs With: separação de responsabilidades

• Where restringe quais objetos entram no resultado.
• With filtra blocos de dados aninhados dentro dos objetos selecionados.

Essa separação se reflete diretamente na forma da consulta no servidor.

---

Tradução da consulta no servidor e volume de dados

Duas regras valem quando uma consulta é executada:

1. A consulta é traduzida para uma forma do lado do servidor — veja o exemplo abaixo.
2. O conjunto de campos solicitados depende de quais dados são lidos no código.

Nem todos os campos são solicitados automaticamente. O analisador de código detecta quais campos são lidos e monta a requisição ao servidor de acordo — os demais campos permanecem NULL.

aviso

Um campo pode permanecer NULL se não estiver incluído no formato da consulta. Esse comportamento está atrelado a quais campos são lidos no código.

---

Trabalhando com vários Models e expandindo relações

A linguagem de consulta permite trabalhar com vários Models e expande automaticamente as relações aninhadas com base no Schema.

Exemplo de descrição de relações entre Models:

Player {
  InventoryItems = InventoryItem {
    Creator = Player
  }
  Clan = Clan {
    King = Player
  }
}

---

Extensões de Model em qualquer nível de aninhamento

Se um Model tem extensões próprias, elas valem independentemente do nível de aninhamento em que o Model é obtido.

player.InventoryItems[3].Creator.Trade();

---

Restrição das condições: apenas Expression

Um Handler passado para Where ou With precisa ser uma Expression. Use Expression<Func<T,bool>> na interface de consulta.

Where e With exigem análise de código, que constrói uma consulta DSL a partir da condição e bloqueia instruções não suportadas.

---

Forma da consulta no servidor

A consulta em estilo LINQ é traduzida para uma forma do lado do servidor. As condições de Where restringem a seleção de objetos, enquanto as de With filtram os dados aninhados. Por exemplo, esta consulta:

var players = await PlayServ.Model<Player>()
  .Where(player => player.Age > 15)
  .Where(player => player.Clan.King.Age > 25)
  .With(p => p.InventoryItems.Price < 500)
  .With(p => p.InventoryItems.Creator.Race == "Gnome");

é traduzida para:

Player(where: {
  Age: {_gt: 15}
  Clan: { King: { Age: {_gt: 25}}}
}) {
  Name
  Age
  InventoryItems(where: {Price: {_lt: 500}}) {
    Name
    Creator(where: {Race: {_eq: "Gnome"}}) {
      Name
      Race
    }
  }
  Clan {
    Name
    King {
      Name
      Age
    }
  }
}

---

Próximos passos

• Data Subscriptions & Live Updates — assine mudanças de dados ao vivo: Subscriptions de consulta, Wait<Update>, Stop()
• Data Mutation & Model Extending — Update() / Delete() e a extensão de Models com métodos