Skip to content

Commit

Permalink
fix documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
agrgr committed Feb 6, 2024
1 parent 9e3e246 commit f936863
Showing 1 changed file with 13 additions and 20 deletions.
33 changes: 13 additions & 20 deletions src/main/asciidoc/reference/aerospike-object-mapping.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -13,43 +13,36 @@ For more details refer to SpringData documentation:

`AerospikeMappingConverter` has a few conventions for mapping objects to documents when no additional mapping metadata is provided. The conventions are:


[[mapping-conventions-id-field]]
=== How the '_id' Field Is Handled in the Mapping Layer

AerospikeDB requires that you have an '_id' field for all objects. If you don't provide one the driver will assign a ObjectId with a generated value. The "_id" field can be of any type, other than arrays, so long as it is unique. The driver naturally supports all primitive types and Dates. When using the `AerospikeMappingConverter` there are certain rules that govern how properties from the Java class are mapped to this '_id' field.
=== How the 'id' Field Is Handled in the Mapping Layer

The following outlines what field will be mapped to the '_id' document field:
Aerospike DB requires that you have an `id` field for all objects. The `id` field can be of any primitive type as well as `String` or `byte[]`.

* A field annotated with `@Id` (`org.springframework.data.annotation.Id`) will be mapped to the '_id' field.
* A field without an annotation but named 'id' will be mapped to the '_id' field.
* The default field name for identifiers is '_id' and can be customized via the `@Field` annotation.
The following table outlines the requirements for the `id` field:

[cols="1,2", options="header"]
.Examples for the translation of '_id'-field definitions
|===
| Field definition
| Resulting Id-Fieldname in AerospikeDB
| Description

| `String` id
| `_id`
| A field named 'id' without an annotation

| `@Field` `String` id
| `_id`

| `@Field('x')` `String` id
| `x`
| A field annotated with `@Id` (`org.springframework.data.annotation.Id`)

| `@Id` `String` x
| `_id`
| `@Id` `String` customNamedIdField

| `@Field('x')` `@Id` `String` x
| `_id`
|===

The following outlines what type of conversion, if any, will be done on the property mapped to the _id document field.
The following description outlines what type of conversion, if any, will be done on the property mapped to the `id` document field:

* By default, the type of the field annotated with `@id` is turned into a `String` to be stored in Aerospike database. If the original type cannot be persisted (see xref:#configuration.keep-original-key-types[keepOriginalKeyTypes] for details), it must be convertible to `String` and will be stored in the database as such, then converted back to the original type when the object is read. This is transparent to the application but needs to be considered if using external tools like `AQL` to view the data.
* By default, the type of the field annotated with `@id` is turned into a `String` to be stored in Aerospike database.
If the original type cannot be persisted (see xref:#configuration.keep-original-key-types[keepOriginalKeyTypes]
for details), it must be convertible to `String` and will be stored in the database as such,
then converted back to the original type when the object is read. This is transparent to the application
but needs to be considered if using external tools like `AQL` to view the data.
* If no field named "id" is present in the Java class then an implicit '_id' file will be generated by the driver but not mapped to a property or field of the Java class.

When querying and updating `AerospikeTemplate` will use the converter to handle conversions of the `Query` and `Update` objects that correspond to the above rules for saving documents so field names and types used in your queries will be able to match what is in your domain classes.
Expand Down

0 comments on commit f936863

Please sign in to comment.