Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs

Crie entidades para representar coleções

Neste guia, você pode aprender como criar entidades ORM do Hibernar que representam coleções MongoDB. As entidades são classes Java que definem a estrutura dos seus dados. Ao usar a extensão Hibernate ORM, você pode mapear cada entidade para uma coleção MongoDB e usar essas entidades para a interação com os documentos da coleção.

Dica

Tutorial de entidades

Para visualizar um tutorial que mostra como modelar relacionamentos um-para-muitos usando entidades e a extensão ORM do Hibername, consulte a publicação no blog Modelando relacionamentos com ORM do Hibername e MongoDB Foojay.

O MongoDB organiza e armazena documentos em uma representação binária chamada BSON que permite o em processamento de dados flexíveis. Esta seção descreve o suporte da extensão Hibername ORM para campos BSON, que você pode incluir em suas entidades.

Dica

Para saber mais sobre como o MongoDB armazena dados BSON, consulte tipos de BSON no manual do MongoDB Server .

A tabela a seguir descreve os tipos de campo BSON suportados e seus equivalentes de extensão Hibername ORM que você pode usar em suas entidades Hibername ORM:

Tipo de campo BSON
Tipo de campo de extensão
Descrição do JSON

null

null

Representa um valor nulo ou ausência de dados.

Binary

byte[]

Armazena dados binários com subtipo 0.

String

char, java.lang.Character, java.lang.String ou char[]

Armazena valores de string codificados em UTF-8.

Int32

int ou java.lang.Integer

Armazena números inteiros assinados de 32bits.

Int64

long ou java.lang.Long

Armazena números inteiros assinados de 64bits.

Double

double ou java.lang.Double

Armazena valores de ponto flutuante.

Boolean

boolean ou java.lang.Boolean

Armazena valores true ou false.

Decimal128

java.math.BigDecimal

Armazena valores decimais de 28bits.

ObjectId

org.bson.types.ObjectId

Armazena identificadores exclusivos de 12bytes que o MongoDB usa como chaves primárias.

Date

java.time.Instant

Armazena datas e horas em milésimos de segundo desde a época do Unix.

Object

@org.hibernate.annotations.Struct agregado incorporável

Armazena documentos incorporados com valores de campo mapeados de acordo com seus respectivos tipos. @Struct incorporáveis agregados também podem conter atributos de array ou Collection.

Array

Array, java.util.Collection (ou subtipo) de tipos suportados

Armazena valores de array com elementos mapeados de acordo com seus respectivos tipos. As arrays de caracteres exigem a definição da propriedade de configuração hibernate.type.wrapper_array_handling.

Para criar uma entidade que represente uma coleção MongoDB , crie um novo arquivo Java no diretório do pacote base do seu projeto e adicione sua classe de entidade ao novo arquivo. Na sua classe de entidade, especifique os campos que você deseja armazenar e o nome da coleção. O elemento name da anotação @jakarta.persistence.Table representa seu nome de coleção MongoDB . Use a seguinte sintaxe para definir uma entidade:

@Entity
@Table(name = "<collection name>")
public class <EntityName> {
@Id
// Specify your primary key field here
private <field type> <field name>;
// Include additional fields here
private <field type> <field name>;
// Parameterized constructor
public <EntityName>(<parameters>) {
// Initialize fields here
}
// Default constructor
public <EntityName>() {
}
// Getter and setter methods
public <field type> get<FieldName>() {
return <field name>;
}
public void set<FieldName>(<field type> <field name>) {
this.<field name> = <field name>;
}
}

Para utilizar suas entidades, você pode fazer query neles em seus arquivos do aplicativo. Para saber mais sobre as Operações CRUD na extensão ORM do Hibernate, consulte o guia Executar Operações CRUD.

Esta classe de entidade do Movie.java de amostra define uma entidade do Movie que inclui as seguintes informações:

  • @Entity anotação que marca a classe como uma entidade ORM do Hibernar

  • @Table anotação que mapeia a entidade para a coleção movies a partir dos conjuntos de dados de amostra do Atlas

  • @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária e configuram a geração automática de ObjectId

    Dica

    Valores de chave primária

    Este exemplo especifica o campo ObjectId como a chave primária da entidade, mas você também pode definir os campos String, Int ou UUID como a chave primária usando a anotação @Id.

  • Campos privados que representam dados do filme

  • Construtores padrão e parametrizados para instanciação de entidade

  • Métodos de getter e setter que fornecem acesso aos campos da entidade

package org.example;
import com.mongodb.hibernate.annotations.ObjectIdGenerator;
import org.bson.types.ObjectId;
import java.util.List;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
@Entity
@Table(name = "movies")
public class Movie {
@Id
@ObjectIdGenerator
private ObjectId id;
private String title;
private String plot;
private int year;
private List<String> cast;
public Movie(String title, String plot, int year, List<String> cast) {
this.title = title;
this.plot = plot;
this.year = year;
this.cast = cast;
}
public Movie() {
}
public ObjectId getId() {
return id;
}
public String getTitle() {
return title;
}
public void setTitle(String title) {
this.title = title;
}
public String getPlot() {
return plot;
}
public void setPlot(String plot) {
this.plot = plot;
}
public int getYear() {
return year;
}
public void setYear(int year) {
this.year = year;
}
public List<String> getCast() {
return cast;
}
public void setCast(List<String> cast) {
this.cast = cast;
}
}

Dica

Para saber mais sobre os campos usados na definição da classe de entidade, consulte a seção MongoDB BSON Fields deste guia.

A extensão Hibernate ORM suporta documentos incorporados por meio de anotações do Hibernate ORM @Embeddable. Com documentos incorporados, você pode criar relacionamentos um-para-muitos, muitos-para-um e um-para-um nos documentos do MongoDB. Esse formato é ideal para representar dados que são acessados juntos com frequência.

Para representar documentos incorporados, use as anotações @Struct e @Embeddable em uma classe para criar um agregado @Struct incorporável. Em seguida, inclua o tipo incorporável em sua entidade principal como um campo. A extensão Hibernate ORM oferece suporte à incorporação de objetos únicos, arrays e coleções de incorporáveis.

Dica

Para aprender mais sobre @Struct incorporáveis agregados, consulte @Struct mapeamento de incorporáveis agregados na documentação ORM do Hibernate.

Um relacionamento um-para-um é quando um registro em um banco de dados está associado a exatamente um registro em outro banco de dados. No MongoDB , você pode criar uma coleção com um campo de documento incorporado para modelar um relacionamento um-para-um. A extensão Hibername ORM permite criar campos de documento incorporado usando @Struct embeddables agregados.

O exemplo define um campo com um tipo incorporável agregado @Struct em uma entidade semelhante ao exemplo Definir uma entidade neste guia. A classe de entidade de amostra Movie.java inclui as seguintes informações:

  • @Entity e anotações @Table que definem a entidade e a mapeiam para a coleção movies

  • @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária

  • campo de string que representa o título do filme

  • @Struct campos incorporáveis agregados que representam prêmios de filme e informações do atlas

O exemplo a seguir representa um relacionamento um-para-um porque cada entidade Movie está associada a um Awards incorporável e a um Studio incorporável:

@Entity
@Table(name = "movies")
public class Movie {
@Id
@ObjectIdGenerator
private ObjectId id;
private String title;
private Awards awards;
private Studio studio;
public Movie(String title, Awards awards, Studio studio) {
this.title = title;
this.awards = awards;
this.studio = studio;
}
public Movie() {
}
// Getter and setter methods
}

O seguinte código de amostra cria um agregado Awards @Struct incorporável:

@Embeddable
@Struct(name = "Awards")
public class Awards {
private int wins;
private int nominations;
private String text;
public Awards(int wins, int nominations, String text) {
this.wins = wins;
this.nominations = nominations;
this.text = text;
}
public Awards() {
}
// Getter and setter methods
}

O seguinte código de amostra cria um agregado Studio @Struct incorporável:

@Embeddable
@Struct(name = "Studio")
public class Studio {
private String name;
private String location;
private int foundedYear;
public Studio(String name, String location, int foundedYear) {
this.name = name;
this.location = location;
this.foundedYear = foundedYear;
}
public Studio() {
}
// Getter and setter methods
}

Um relacionamento um-para-muitos é quando um registro em um banco de dados está associado a muitos registros em outro banco de dados. No MongoDB, você pode definir um campo de coleção que armazena uma lista de documentos incorporados para modelar um relacionamento um-para-muitos. A extensão Hibername ORM permite criar campos de documento incorporado usando uma lista de @Struct incorporáveis agregados.

O exemplo define um campo que armazena uma lista de @Struct incorporáveis agregados em uma entidade semelhante ao Exemplo de Definir uma Entidade neste guia. A classe de entidade de amostra Movie.java inclui as seguintes informações:

  • @Entity e anotações @Table que definem a entidade e a mapeiam para a coleção movies

  • @Id e @ObjectIdGenerator anotações que designam o campo id como a chave primária

  • campo de string que representa o título do filme

  • campo de lista que armazena vários embeddables agregados do Writer @Struct, que representa informações do escritor

O exemplo a seguir representa um relacionamento um-para-muitos porque cada entidade Movie está associada a vários incorporáveis Writer:

@Entity
@Table(name = "movies")
public class Movie {
@Id
@ObjectIdGenerator
@Column(name = "_id")
private ObjectId id;
private String title;
private List<Writer> writers;
public Movie(String title, List<Writer> writers) {
this.title = title;
this.writers = writers;
}
public Movie() {
}
// Getter and setter methods
}

O seguinte código de amostra cria um agregado Writer @Struct incorporável:

@Embeddable
@Struct(name = "Writer")
public class Writer {
private String name;
public Writer() {
}
public Writer(String name) {
this.name = name;
}
// Getter and setter methods
}

Para saber como usar suas entidades para executar operações de banco de dados, consulte os seguintes guias na seção Interação com dados:

Para aprender mais sobre os campos do ORM do Hibernate, consulte a Tipos de mapeamento na documentação do ORM do Hibernate.

Para aprender mais sobre entidades ORM do Hibernate, veja Modelos POJO na documentação ORM do Hibernate.