Defining Indexes Using JPA’s @Index Annotation

1. Introduction

En este tutorial, discutiremos la definición de índices utilizando la anotación @Index de JPA. A través de ejemplos, aprenderemos cómo definir nuestro primer índice utilizando JPA y Hibernate. Después de eso, modificaremos la definición mostrando formas adicionales de personalizar el índice.

@Index Annotation

Empecemos con un breve resumen. El índice de base de datos es una estructura de datos que mejora la velocidad de las operaciones de recuperación de datos en una tabla a costa de escritorios y espacio de almacenamiento adicionales. Principalmente, es una copia de columnas seleccionadas de datos de una sola tabla. Debemos crear índices para aumentar el rendimiento en nuestra capa de persistencia.

JPA nos permite lograr esto definiendo índices desde nuestro código utilizando @Index. Esta anotación es interpretada por el proceso de generación de esquema, creando automáticamente artefactos. Cabe señalar que no es necesario especificar ningún índice para nuestras entidades.

2.1. jakarta.persistence.Index

El soporte para índices se añadió finalmente en la especificación JPA 2.1 a través de jakarta.persistence.Index. Esta anotación nos permite definir un índice para nuestra tabla y personalizarlo en consecuencia:

@Target({})
@Retention(RUNTIME)
public @interface Index {
    String name() default "";
    String columnList();
    boolean unique() default false;
}

Como podemos ver, solo el atributo columnList es obligatorio, que debe definirse. Más adelante, observaremos más de cerca cada uno de los parámetros, pasando por ejemplos.

Un aspecto a tener en cuenta aquí es que la anotación no soporta cambiar el algoritmo de indexación por defecto — btree.

2.2. JPA vs. Hibernate

Sabemos que JPA es solo una especificación. Para trabajar correctamente, también necesitamos especificar un proveedor de persistencia. Por defecto, el framework Hibernate es la implementación de JPA proporcionada por Spring. Más sobre esto puedes leer aquí.

Recordemos que el soporte de índices se ha agregado a JPA muy tarde. Antes de eso, muchos frameworks ORM daban soporte a índices al introducir su propia implementación personalizada, que podría funcionar de manera diferente. El framework Hibernate también lo hizo e introdujo la anotación org.hibernate.annotations.Index. Al trabajar con ese framework, debemos tener cuidado ya que ha sido descontinuada desde el soporte de la especificación JPA 2.1, y debemos usar la de JPA.

Ahora que tenemos algo de contexto técnico, podemos pasar a los ejemplos y definir nuestro primer índice en JPA.

3. Defining the @Index

En esta sección, implementaremos nuestro índice. Más adelante, intentaremos modificarlo, presentando diferentes posibilidades de personalización.

Antes de comenzar, necesitamos inicializar nuestro proyecto adecuadamente y definir un modelo.

Ejemplo básico con una entidad `Student`

Implementemos una entidad Student:

@Entity
@Table
public class Student implements Serializable {
    @Id
    @GeneratedValue
    private Long id;
    private String firstName;
    private String lastName;

    // getters, setters
}

Cuando tenemos nuestro modelo, implementemos el primer índice. Todo lo que debemos hacer es agregar una anotación @Index. Hacemos esto en la anotación @Table debajo del atributo indexes. Recordemos especificar el nombre de la columna:

@Table(indexes = @Index(columnList = "firstName"))

Hemos declarado el primer índice utilizando la columna firstName. Cuando ejecutamos el proceso de creación de esquema, podemos validarlo:

[main] DEBUG org.hibernate.SQL -
  create index IDX2gdkcjo83j0c2svhvceabnnoh on Student (firstName)

Ahora, es momento de modificar nuestra declaración mostrando características adicionales.

@Index Name

Como podemos ver, nuestro índice debe tener un nombre. Por defecto, si no especificamos uno, es un valor generado por el proveedor. Cuando queremos tener una etiqueta personalizada, simplemente debemos agregar el atributo name:

@Index(name = "fn_index", columnList = "firstName")

Esta variante crea un índice con un nombre definido por el usuario:

[main] DEBUG org.hibernate.SQL -
  create index fn_index on Student (firstName)

Además, podemos crear nuestro índice en un esquema diferente especificando el nombre del esquema en el name:

@Index(name = "schema2.fn_index", columnList = "firstName")

3.2. Multicolumn @Index

Ahora, veamos más de cerca la sintaxis del columnList:

column ::= index_column [,index_column]*
index_column ::= column_name [ASC | DESC]

Como ya sabemos, podemos especificar los nombres de las columnas que se incluirán en el índice. Por supuesto, podemos especificar múltiples columnas para un único índice. Hacemos esto separando los nombres por una coma:

@Index(name = "mulitIndex1", columnList = "firstName, lastName")

@Index(name = "mulitIndex2", columnList = "lastName, firstName")

Nota que el proveedor de persistencia debe observar el orden especificado de las columnas. En nuestro ejemplo, los índices son ligeramente diferentes, incluso si especifican el mismo conjunto de columnas.

[main] DEBUG org.hibernate.SQL -
  create index mulitIndex1 on Student (firstName, lastName)

[main] DEBUG org.hibernate.SQL -
  create index mulitIndex2 on Student (lastName, firstName)

3.3. @Index Order

Como revisamos en la sección anterior, también podemos especificar valores ASC (ascendente) y DESC (descendente) después del column_name. Los usamos para establecer el orden de clasificación de los valores en la columna indexada:

@Index(name = "mulitSortIndex", columnList = "firstName, lastName DESC")

Podemos especificar el orden para cada columna. Si no lo hacemos, se asume el orden ascendente.

[main] DEBUG org.hibernate.SQL -
  create index mulitSortIndex on Student (firstName, lastName desc)

3.4. @Index Uniqueness

El último parámetro opcional es un atributo unique, que define si el índice es único. Un índice único asegura que los campos indexados no almacenen valores duplicados. Por defecto, es false. Si queremos cambiarlo, podemos declararlo así:

@Index(name = "uniqueIndex", columnList = "firstName", unique = true)

Cuando creamos un índice de esa manera, añadimos una restricción de unicidad en nuestras columnas, similar a como un atributo unique en la anotación @Column lo haría. La anotación @Index tiene la ventaja sobre @Column debido a la posibilidad de declarar una restricción de unicidad de múltiples columnas:

@Index(name = "uniqueMulitIndex", columnList = "firstName, lastName", unique = true)

3.5. Multiple @Index on a Single Entity

Hasta ahora, hemos implementado diferentes variantes del índice. Por supuesto, no estamos limitados a declarar un solo índice en la entidad. Recopilemos nuestras declaraciones y especifiquemos cada índice a la vez. Hacemos esto repitiendo la anotación @Index entre llaves y separándolas por una coma:

@Entity
@Table(indexes = {
  @Index(columnList = "firstName"),
  @Index(name = "fn_index", columnList = "firstName"),
  @Index(name = "mulitIndex1", columnList = "firstName, lastName"),
  @Index(name = "mulitIndex2", columnList = "lastName, firstName"),
  @Index(name = "mulitSortIndex", columnList = "firstName, lastName DESC"),
  @Index(name = "uniqueIndex", columnList = "firstName", unique = true),
  @Index(name = "uniqueMulitIndex", columnList = "firstName, lastName", unique = true)
})
public class Student implements Serializable

¿Qué más? También podemos crear múltiples índices para el mismo conjunto de columnas.

3.6. Primary Key

Cuando hablamos de índices, debemos detenernos un momento en las claves primarias. Como sabemos, cada entidad gestionada por el EntityManager debe especificar un identificador que se asigna a la clave primaria.

Generalmente, la clave primaria es un tipo específico de índice único. Vale la pena agregar que no tenemos que declarar la definición de esta clave de la manera presentada antes. Todo se hace automáticamente a través de la anotación @Id.

3.7. Non-entity @Index

Después de que hemos aprendido diferentes maneras de implementar índices, debemos mencionar que @Table no es el único lugar para especificarlos. Del mismo modo, podemos declarar índices en las anotaciones @SecondaryTable, @CollectionTable, @JoinTable, @TableGenerator. Estos ejemplos no se cubren en este artículo. Para más detalles, consulta la JavaDoc de jakarta.persistence.

4. Conclusion

En este artículo, discutimos cómo declarar índices utilizando JPA. Comenzamos revisando el conocimiento general sobre ellos. Posteriormente, implementamos nuestro primer índice y, a través de ejemplos, aprendimos cómo personalizarlo cambiando el nombre, las columnas incluidas, el orden y la unicidad. Al final, hablamos sobre las claves primarias y las maneras y lugares adicionales donde podemos declararlas.

Consejos Prácticos

Evalúa el rendimiento: Al declarar índices, evalúa cómo pueden afectar el rendimiento de las operaciones de escritura. Aunque mejoran la recuperación de datos, pueden afectar la inserción y actualización de registros.
Monitoriza el uso de los índices: Utiliza herramientas de monitorización para entender cuáles índices son utilizados y cuáles no. Esto te ayudará a optimizar la estructura de la base de datos.
Revisión de índices periódica: A medida que tu aplicación evoluciona, revisa y ajusta los índices para que sigan alineados con los patrones de acceso de tus datos.
Cuidado con la unicidad: Si utilizas índices únicos, asegúrate de entender las implicaciones en la integridad de los datos y en el manejo de excepciones durante las inserciones y actualizaciones.
Consulta la documentación: Mantente al día con las últimas actualizaciones de JPA y Hibernate para aprovechar nuevas mejoras y prácticas recomendadas.

Este sencillo enfoque a los índices en JPA no solo respaldará el rendimiento de tu aplicación, sino que también proporcionará una base sólida para futuras optimizaciones. ¡Feliz codificación!

Definiendo Índices con la Anotación JPA