HHH-16152 Documentation for @PartitionKey

This commit is contained in:
Christian Beikov 2023-02-08 15:00:56 +01:00
parent f33e89133e
commit b918909359
4 changed files with 153 additions and 0 deletions

View File

@ -1184,6 +1184,13 @@ The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibern
See the <<chapters/domain/embeddables.adoc#embeddable-Parent,`@Parent` mapping>> section for more info.
[[annotations-hibernate-partition-key]]
==== `@PartitionKey`
The https://docs.jboss.org/hibernate/orm/{majorMinorVersion}/javadocs/org/hibernate/annotations/PartitionKey.html[`@PartitionKey`] annotation is used to identify a field of an entity that holds the partition key of a table.
See the <<chapters/domain/embeddables.adoc#embeddable-Parent,`@PartitionKey` mapping>> section for more info.
[[annotations-hibernate-persister]]
==== `@Persister`

View File

@ -32,6 +32,7 @@ include::identifiers.adoc[]
include::associations.adoc[]
include::collections.adoc[]
include::natural_id.adoc[]
include::partitioning.adoc[]
include::dynamic_model.adoc[]
include::inheritance.adoc[]
include::immutability.adoc[]

View File

@ -0,0 +1,41 @@
[[partitioning]]
=== Partitioning
:root-project-dir: ../../../../../../..
:documentation-project-dir: {root-project-dir}/documentation
:example-dir-partition-key: {documentation-project-dir}/src/test/java/org/hibernate/userguide/mapping/identifier
:extrasdir: extras
In data management, it is sometimes necessary to split data of a table into various (physical) partitions,
based on partition keys and a partitioning scheme.
Due to the nature of partitioning, it is vital for the database to know the partition key of a row for certain operations,
like SQL update and delete statements. If a database doesn't know the partition of a row that should be updated or deleted,
then it must look for the row in all partitions, leading to poor performance.
The `@PartitionKey` annotation is a way to tell Hibernate about the column, such that it can include a column restriction as
predicate into SQL update and delete statements for entity state changes.
[[partition-key-mapping]]
==== Partition Key Mapping
Partition keys are defined in terms of one or more persistent attributes.
[[partition-key-simple-basic-attribute-mapping-example]]
.Partition key using single basic attribute
====
[source,java]
----
include::{example-dir-partition-key}/SimplePartitionKeyTest.java[tags=partition-key-simple-basic-attribute-mapping-example,indent=0]
----
====
When updating or deleting an entity, Hibernate will include a partition key constraint similar to this
[[partition-key-simple-basic-attribute-sql-example]]
====
[source,sql]
----
update user_tbl set firstname=?,lastname=?,tenantKey=? where id=? and tenantKey=?
delete from user_tbl where id=? and tenantKey=?
----
====

View File

@ -0,0 +1,104 @@
/*
* Hibernate, Relational Persistence for Idiomatic Java
*
* License: GNU Lesser General Public License (LGPL), version 2.1 or later.
* See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
*/
package org.hibernate.userguide.mapping.identifier;
import org.hibernate.annotations.PartitionKey;
import org.hibernate.orm.test.jpa.BaseEntityManagerFunctionalTestCase;
import org.junit.Test;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import static org.hibernate.testing.transaction.TransactionUtil.doInJPA;
/**
* @author Christian Beikov
*/
public class SimplePartitionKeyTest extends BaseEntityManagerFunctionalTestCase {
@Override
protected Class<?>[] getAnnotatedClasses() {
return new Class<?>[] {
User.class
};
}
@Test
public void test() {
doInJPA(this::entityManagerFactory, entityManager -> {
User user = new User();
user.setId( 1L );
user.setFirstname( "John" );
user.setLastname( "Doe" );
user.setTenantKey( "tenant1" );
entityManager.persist( user );
});
doInJPA( this::entityManagerFactory, entityManager -> {
User user = entityManager.find( User.class, 1L );
user.setLastname( "Cash" );
} );
doInJPA( this::entityManagerFactory, entityManager -> {
entityManager.remove( entityManager.find( User.class, 1L ) );
} );
}
@Table(name = "user_tbl")
//tag::partition-key-simple-basic-attribute-mapping-example[]
@Entity(name = "User")
public static class User {
@Id
private Long id;
private String firstname;
private String lastname;
@PartitionKey
private String tenantKey;
//Getters and setters are omitted for brevity
//end::partition-key-simple-basic-attribute-mapping-example[]
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getFirstname() {
return firstname;
}
public void setFirstname(String title) {
this.firstname = title;
}
public String getLastname() {
return lastname;
}
public void setLastname(String author) {
this.lastname = author;
}
public String getTenantKey() {
return tenantKey;
}
public void setTenantKey(String tenantKey) {
this.tenantKey = tenantKey;
}
//tag::partition-key-simple-basic-attribute-mapping-example[]
}
//end::partition-key-simple-basic-attribute-mapping-example[]
}