Below is a list of all Achilles annotations.
This annotation indicates which field is a clustering column.
Put this annotation on several fields to have many clustering columns.
The attribute value indicates the ordering of this clustering column.
If you want to store the data in reversed order, set the attribute asc to false
The attribute asc indicates the sorting order. By default asc = true
Unlike Java indexes, the ordering starts at 1. It is a design choice since it is more natural for human being to start counting at 1
@Table
public class MyEntity
{
@PartitionKey
private Long userId;
@ClusteringColumn(value = 1, asc = false)
private Date date;
@ClusteringColumn(2)
private String type;
...
}
Define a custom codec system to encode any Java type into Cassandra-compatible types.
The provided Codec class should implement the Codec interface.
Let's consider the following codec transforming a Long to a String
public class LongToString implements Codec<Long,String> {
@Override
public Class<Long> sourceType() {
return Long.class;
}
@Override
public Class<String> targetType() {
return String.class;
}
@Override
public String encode(Long fromJava) throws AchillesTranscodingException {
return fromJava.toString();
}
@Override
public Long decode(String fromCassandra) throws AchillesTranscodingException {
return Long.parseLong(fromCassandra);
}
}
Example of simple Long type to String type transformation
@Column
@Codec(LongToString.class)
private Long longToString;
@Column
private List<@Codec(LongToString.class) Long> listOfLongToString;
@Column
private Map<Integer, @Codec(LongToString.class) Long> mapOfLongToStringValue;
Marker annotation to be used on configuration class for compile-time code generation. The type (class,abstract class or interface) having this annotation will expose a list of codecs to be used by Achilles
during source code parsing.
Ex:
@CodecRegistry
public [class | abstract class | interface] MyCodecRegistry {
//Source type = int, target type = String (according to IntToStringCodec codec)
@Codec(IntToStringCodec.class)
private int intToString;
//Source type = MyOwnType, target type = String (according to MyOwnTypeToStringCodec codec)
@Codec(MyOwnTypeToStringCodec.class)
private MyOwnType myOwnTypeToString;
//Source type = AnotherBean, target type = String (because of {@literal @}JSON)
@JSON
private AnotherBean beanToJSON;
//Source type = MyEnum, target type = int (because of Encoding.ORDINAL)
@Enumerated(Encoding.ORDINAL)
private MyEnum enumToOrdinal;
} See Codec Registry for more details
Indicates a field to be mapped by Achilles. When the value attribute of @Column is given, the field
will be mapped to this name. Otherwise the field name will be used.
Example:
@Column("age_in_years")
private Long age;
Remark: the custom
valueset on a column will override any Naming Strategy defined on the table/globally.
The case of the column name defined with @Column will be respected by Achilles and if the column name has mixed upper & lower cases, Achilles will enclose it between double quotes when creating the table.
Example:
@Column("itemsCount")
private Long itemsCount;
The generated DDL script would be:
CREATE TABLE ...
(
...
"itemsCount" bigint,
...
)Similarly, all generated CQL statements will enquote the column name.
You can specify configuration parameters at compie time using the CompileTimeConfig as below:
@CompileTimeConfig(cassandraVersion = CassandraVersion.CASSANDRA_3_0_X)
public interface AchillesConfig {
}Depending on the chosen version, Achilles will generate appropriate DSL code.
You can also specify the column mapping strategy, naming strategy, insert strategy and the project name.
See Configuring Achilles at compile time for more details.
This annotation defines a computed column e.g. a column generated by a function call.
For example to define the column writetime(value):
@Table
public class Entity {
...
@Column
private String value;
@Computed(function = "writetime", alias="writetime_value", targetColumns = {"value"}, cqlClass = Long.class)
private Long valueWriteTime;
}This annotation defines 4 attributes:
writetime() or an user defined function
@Table
public class Entity {
...
@Column("first_name")
private String firstname;
@Computed(function = "writetime", alias="writetime_firstname", targetColumns = {"first_name"}, cqlClass = Long.class)
private Long valueWriteTime;
}In the above example, targetColumns should point to first_name, which is the CQL column, and not firstname
which represents the Java field name
This annotation should be used on an entity
You need to specify the read, write and serial attribute to define the corresponding consistency level.
Example:
@Table
@Consistency(read=ConsistencyLevel.ONE, write=ConsistencyLevel.QUORUM, serial=ConsistencyLevel.SERIAL)
public class Entity
{
...
}
For collections and maps, Cassandra does not distinguish between empty collection/map and null collection/map.
Therefore if you save an empty list, it is equivalent to setting null to this list, thus deleting it. When reading back the list, Cassandra will return a null value so Achilles will map back to a null list.
To avoid having to check for null, you can add the @EmptyCollectionIfNull annotation on a collection or map, Achilles will then map null value to an empty instance of the collection/map.
Define the encoding for enum values. There are 2 defined encoding types: Encoding.NAME and Encoding.ORDINAL, which use respectively the enum name & ordinal
for encoding.
Example:
@Column(name = "pricing")
@Enumerated(Encoding.ORDINAL)
private Pricing pricing;
@Column(name = "pricings")
private List<@Enumerated(Encoding.ORDINAL) Pricing> pricings;
@Column(name = "pricing_per_country")
private Map<@Enumerated(Encoding.ORDINAL) Country, @Enumerated(Encoding.ORDINAL) PricingType> pricingPerCountry; More details on Enum type
Define a frozen UDT or nested frozen UDT/collection
@Table
public class Entity {
@Column
@Frozen
private MyUDT myUdt;
@Column
private List<@Frozen MyUDT> udtList;
@Column
private List<@Frozen Map<Integer, String>> nestedCollection;
}Marks a class as a function registry and let Achilles manage it
@FunctionRegistry
public interface MyFunctions {
Integer sumOf(int val1, int val2);
Long toLong(Date javaDate);
}Note: it is possible to declare several function registries in your source code, just annotate them with @FunctionRegistry
Warning: it is not possible to declare 2 different functions with the same name and signature in the same keyspace
Achilles will raise a compilation error when encountering such case. Ex:
@FunctionRegistry
public interface MyFunctionRegistry {
String toString(long value);
String toString(int value); // OK because parameter type is different
String toString(long value); // KO because same signature as the first function
}Remark 1: functions return types cannot be primitive, use boxed types instead
Remark 2: Achilles' codec system also applies for function parameters and return type
@FunctionRegistry
public interface FunctionsWithCodecSystemRegistry {
// CQL function signature = listtojson(consistencylevels list<text>), returns text
String listToJson(List<@Enumerated ConsistencyLevel> consistencyLevels);
// CQL function signature = getinvalue(input text), returns text
@Codec(IntToString.class) String getIntValue(String input);
}Remark 3: functions name and parameters' name are lower-cased by Cassandra automatically
The @FunctionRegistry annotation accepts a keyspace attribute to specify in which keyspace the declared
functions belong to. If not specified the currently logged keyspace will be used.
See Functions Mapping for more details
This annotation defines a secondary index on a regular column
Additionally you can define the name of the index using the name attribute on the annotation.
Example
@Table
public class User {
@PartitionKey
private Long id;
//Simple index
@Column
@Index
private String countryCode;
//Simple index with custom name
@Column("custom_name")
@Index(name = "country_code_idx")
private String customName;
//Index on collection
@Column
@Index
private List<String> indexedList;
//Full index on collection because of the usage of @Frozen
@Column
@Frozen
@Index
private List<String> indexedFullList;
//Index on map key
@Column("indexed_map_key")
private Map<@Index String, Long> indexOnMapKey;
//Index on map entry
@Column("index_map_entry")
@Index
private Map<String, Long> indexOnMapEntry;
//Custom index
@Column
@Index(indexClassName = "com.compagny.index.SecondaryIndex", indexOptions = "{'key1': 'value1', 'key2': 'value2'}")
private String custom;
...
}
The above code will generate the following CQL script:
CREATE INDEX IF NOT EXISTS ON my_entity(countryCode);
CREATE INDEX country_code_idx IF NOT EXISTS ON my_entity(custom_name);
CREATE INDEX IF NOT EXISTS ON my_entity(indexedlist);
CREATE INDEX IF NOT EXISTS ON my_entity(FULL(indexedfulllist));
CREATE INDEX IF NOT EXISTS ON my_entity(KEYS(indexed_map_key));
CREATE INDEX IF NOT EXISTS ON my_entity(ENTRY(index_map_entry));
CREATE CUSTOM my_entity_custom_index INDEX IF NOT EXISTS
ON my_entity(custom)
USING 'com.compagny.index.SecondaryIndex'
WITH OPTIONS = {'key1': 'value1', 'key2': 'value2'};
The @Index annotation exposes the following attributes:
Tell Achilles to serialize an un-supported data type into JSON string. Example:
//Simple value encoding
@Column
@JSON
private MyPOJO pojoAsJson;
//Collection value encoding
@Column
private List<@JSON MyPOJO> myPojosAsJson;
//Map key encoding
@Column
private Map<@JSON MyPOJO, String> mapKeyEncoding;
//Map value encoding
@Column
private Map<String, @JSON MyPOJO> mapValueEncoding;
// Tuple value encoding
@Column
private Tuple3<String, @JSON MyPOJO, Integer> tupleValueEncoding;
Marks a class as a materialized view and let Achilles manage it
@MaterializedView(baseEntity = UserEntity.class)
public class UserByCountryView {...}
This annotation defines 3 attributes:
See Materialized View Mapping for more details
This annotation indicates which field is a partition key for the table
Put this annotation on several fields to have a composite partition key.
The attribute value indicates the ordering of this partition component in a composite partition key.
The attribute value defaults to 1.
Unlike Java indexes, the ordering starts at 1. It is a design choice since it is more natural for human being to start counting at 1
private static class Entity
{
@PartitionKey
private Long id;
@ClusteringColumn
private UUID date;
...
}
private static class CompositePartitionEntity
{
@PartitionKey(1)
private Long id;
@PartitionKey(2)
private String type;
@ClusteringColumn
private UUID date;
...
} In the above example, id and type are part of the composite partition key. date is the clustering key.
Remark: all fields annotated with
@PartitionKeyshould be consecutive with respect to their ordering.
Failing this condition will raise an exception during compilation
Transform a custom Java type into one of native types supported by the Java driver. Normally you'll use the @Codec
annotation and provide a codec class but if your codec class is stateful or its construction needs some external
dependencies and cannot be instantiated using the default no-args constructor, you can register the codec using this
annotation and build it at runtime before injecting it into Achilles
Ex:
/Compile time
@Column
@RuntimeCodec(cqlClass = String.class)
private MyBean bean;
//Runtime
final Cluster cluster = .... // Create Java driver cluster object
final Codec<MyBean, String> statefulCodec = new .... // Create your codec with initialization logic here
final CodecSignature<MyBean, String> codecSignature = new CodecSignature(MyBean.class, String.class);
ManagerFactory factory = ManagerFactoryBuilder
.builder(cluster)
...
.withRuntimeCodec(codecSignature, codec)
.build();A codec is looked up and identified uniquely at runtime using the following information:
The @RuntimeCodec annotation has 2 attributes:
Defines a static column
@Table
public class Entity {
@PartitionKey
private Long id;
@Column
@Static
private String staticVal;
@ClusteringColumn
private Date date;
...
} The @Static annotation can only be used in an entity having @ClusteringColumn otherwise Achilles will
raise an exception
Define the insert and naming strategy on an entity.
For the insert strategy, 2 values are possible: info.archinnov.achilles.type.InsertStrategy.NOT_NULL_FIELDS and info.archinnov.achilles.type.InsertStrategy.ALL_FIELDS
Upon call to insert(), depending on the chosen strategy Achilles will
@Table
@Strategy(insert = InsertStrategy.ALL_FIELDS)
public class MyBean
{
@PartitionKey
private Long id;
...
}
Check here for more details on the Insert strategy
For the naming strategy, 3 values are possible: info.archinnov.achilles.type.NamingStrategy.SNAKE_CASE, info.archinnov.achilles.type.NamingStrategy.LOWER_CASE and info.archinnov.achilles.type.NamingStrategy.CASE_SENSITIVE
If not set, the strategy defaults to info.archinnov.achilles.type.NamingStrategy.LOWER_CASE
@Table(keyspace="myKeyspace", table="myTable")
@Strategy(naming = NamingStrategy.SNAKE_CASE)
// final keyspace name will be transformed to 'myKeyspace' and table name to 'myTable' because
// they are defined statically by @Table
public class Entity
{
@PartitionKey
private Long id;
@Column
private String firstName; //column name transformed to 'first_name'
@Column(name = "misc")
private String customInfo; //column name will be 'misc' because name defined on @Column will override any NamingStrategy
...
}
Check here for more details on the Naming strategy
Indicates that an entity is candidate for persistence. By default Achilles creates a table whose name is the short class name of the entity.
If you want to define a specific keyspace name, set the keyspace attribute.
If you want to define a specific table name, set the table attribute.
Example:
@Table(keyspace = "back_end", table="users")
public class User
{
...
...
}
Please note that Cassandra limits the table name to 48 characters max (because of limitations in Windows for file path max lengths)
This annotation tells Achilles to map a Java UUID field to Cassandra timeuuid type.
Example:
@Table
public class Entity
{
@PartitionKey
private Long id;
@TimeUUID
@Column
private UUID date;
...
} This is especially useful in CQL to map to timeuuid type so you can use Timeuuid functions like dateOf()/now()/minTimeuuid()/maxTimeuuid() or unixTimestampOf() on native queries
This annotation should be used on an entity to define the default time to live in seconds
@Table
@TTL(3600) //1h time to live
public class Entity
{
...
}
Put on a JavaBean, this annotation indicates that this class is an UDT
@UDT(keyspace = "my_ks", name="user_udt")
public class UserUDT {
@Column
private String firstname;
@Column
private String lastname;
...
}Then you can re-use the UDT class in another entity
@Table
public class Tweet {
@PartitionKey
private UUID tweetId;
@Column
private String content;
@Column
@Frozen
private UserUDT author;
}It is necessary to use the @Frozen annotation on the UDT field