Please follow these instructions when upgrading from an older Titan release.
This is the first non-milestone release that uses TinkerPop 3. Titan 0.5.x and earlier used TinkerPop 2. Compared with TinkerPop 2, TinkerPop 3 brings substantial changes to Gremlin and to public TP interfaces that Titan implements. Applications written for Titan 0.5.x or TinkerPop 2 will generally require source-level changes to compile or run against Titan 1.0.0 or TinkerPop 3. Since TinkerPop 3 includes GraphComputer for global graph analytics, analytic query processing is now handled by Tinkerpop and Titan only provides the needed input and output formats for the supported big data platforms.
Property pre-fetching is disabled by default in Titan 1.0.0 and future releases. That is, the fast-property configuration settings defaults to true. If you are relying on this setting to speed up multi-property access you need to enable fast-property explicitly.
Titan 0.9.0-M2 uses the same storage format as 0.5.x, but since it’s a milestone release with a lower standard of testing and stability than general availabi
The query language and API have changed considerably. The Titan manual for 0.9.0 is still a work in progress. The TinkerPop 3 documentation is a useful resource for understanding the new API.
Titan 0.9.0-M1 uses the same storage format as 0.5.x, but since it’s a milestone release with a lower standard of testing and stability than general availability releases, it is artificially marked incompatible with all previous versions.
The query language and API have changed considerably. The Titan manual for 0.9.0 is still a work in progress. The TinkerPop 3 documentation is a useful resource for understanding the new API.
Titan 0.5.3 is backwards compatible with 0.5.2, with the exception of one change in the API: StandardTimestamp has been renamed to Timestamp and moved to the com.thinkaurelius.titan.core.attribute package. The storage format is fully backwards compatible.
0.5.2 is backwards compatible with 0.5.0 and 0.5.1. However, 0.5.1 introduced minor API level changes that will affect an upgrade from 0.5.0 to 0.5.2. See the section on 0.5.1 for details. Aside from the changes noted in 0.5.1’s section, 0.5.2 also changed the return type of HadoopPipeline.submit from void to int.
0.5.2 fixed a bug in the titan.sh helper script affecting Cassandra’s data path. In 0.5.0 and 0.5.1, running titan.sh start would fork a Cassandra daemon that stored data, commitlogs, and saved caches in <titan.sh start’s working directory>/db/cassandra. This was a bug. Cassandra’s data directory should be <titan archive root>/db/cassandra, regardless of the titan.sh script’s working directory. This bug only affected the forked Cassandra daemon, not the forked Elasticsearch daemon. This bug is fixed in 0.5.2, so that Cassandra data, commitlogs, and saved caches are always written to <titan archive root>/db/cassandra regardless of the working directory of the titan.sh script. Depending on the working directory used on 0.5.0 and 0.5.1 installs to execute titan.sh start, the db/cassandra directory may need to be copied to the archive root when upgrading to 0.5.2.
0.5.1 (but not 0.5.0) included a copy of both ASM 3.1 and ASM 4.1. These two versions of ASM contain partially overlapping package and classnames with incompatible changes. This conflict between ASM versions could cause class linkage errors when running 0.5.1. 0.5.2 includes only ASM 4.1. Multiple shaded copies of ASM 3.x are retained by dependencies that need an older version. The only module that uses the single unshaded ASM 4.1 dependency is titan-solr.
0.5.1 is backwards compatible with 0.5.0. However, there are some minor API level changes to be aware of.
The schema access methods getPropertyKey(), getEdgeLabel(), and getVertexLabel() do no longer create the key or label if it does not yet exists and become purely retrieval methods that return NULL in this case. Change the method name to getOrCreate/PropertyKey/EdgeLabel/VertexLabel() to invoke the old semantics.
Titan 0.5.0 has introduced a number of new features and seen significant changes to the API. Refer to the documentation for a detailed description of Titan 0.5.0.
Most importantly, Titan 0.5.0 introduces the management system which should be used for schema creation, index building, and other administrative tasks that affect the entire graph. The management system is accessed through g.getManagementSystem() which returns a management transaction that behaves like a normal transaction but provides additional features.
In a management transaction, edge labels and property keys are created with the methods makeEdgeLabel(String) and makePropertyKey(String) respectively. Instead of multiple methods for specifying the multiplicity or cardinality, the builders returned by the respective methods now feature a multiplicity method and a cardinality method, each of which expects an enum argument. The names of the methods in Titan 0.4.x are virtually identical to the enum constants used in Titan 0.5.0.
Note, that schema type definition and index building have been separated in Titan 0.5.0. In older versions, one would call sortKey to build a vertex-centric index for an edge label and indexed to build a global graph index for property keys. These methods have disappeared from the builder and indexes are build separately using the management system. Refer to the relevant sections of the documentation to learn more about building indexes.
|
Note
|
It is still possible to define types in an expicit TitanTransaction, however, it is strongly encouraged to use this method only for those use cases where schema type creation is part of normal user transactions. In all other cases Titan’s management system should be used.
|
Titan 0.5.0 introduces vertex labels as first class schema types. Many applications build on Titan have developed their own vertex labeling / typing system through vertex properties or some other means. It is highly recommended to transition to the native vertex labels supported in Titan 0.5.0.
In previous versions of Titan, the entire graph database configuration had to be provided in a configuration file for each started Titan instance. Starting in 0.5.0, Titan has a central configuration system which stores all configuration properties that must be coordinated across instances. These are initialized from the configuration file used to start the first Titan instance in a new cluster. After that, additional Titan instances only need a minimal configuration to connect to the cluster. Note, that changing global configuration options can no longer be accomplished through changes to the local configuration files. Such changes must now be made through Titan’s management system.
Some configuration options have been renamed and new options have been added. See the [titan-config-ref] for an up-to-date listing of config options.
FullDouble and FullFloat do no longer exist. Use Double and Float instead which are now serialized as 4 and 8 byte floating point numbers. In places where Double or Float was used in sort keys (i.e. as the data type of the property in a sort key), use Decimal and Precision instead, respectively, because they have a fixd decimal range.
The data storage format of Titan 0.5.0 is incompatible with previous releases. The 0.5.0 release does not yet include utilities to automatically convert data stored with previous releases. This is planned for the 0.5.1 release. If a data upgrade is desired before this release, it is encouraged to attempt an export from the old version using the graphson format and import it into a new Titan 0.5.0 graph using Faunus/Titan-Hadoop.
Titan 0.4.1 is fully backwards compatible to Titan 0.4.0 on the data layer. No need to reload or upgrade the data. However, once new types are added to the database through Titan 0.4.1, older versions of Titan cannot read those newly added types. Hence, ensure that all instances of Titan that are accessing the same storage backend are updated before adding new types. Note, that you can have mixed Titan 0.4.0 and 0.4.1 instances reading from the cluster as long as the latter don’t add new types.
Titan 0.4.1 provides some new features that have extended the API, however, those do not break the existing API. There is one change to the API that requires updating. We changed the Text.PREFIX/REGEX to Text.CONTAINS_PREFIX/REGEX to make is obvious what the semantics of those predicates is.
If you are using either of those predicate, rename:
-
Text.PREFIX → Text.CONTAINS_PREFIX
-
Text.REGEX → Text.CONTAINS_REGEX
In Titan 0.4.1 we are storing all Titan flags in the storage backend (i.e. no more local properties file in the data directory). This means, that Titan 0.4.1 will rewrite this flag and ignore its current value. This disables the version compatibility check. Hence, make sure that you are running Titan 0.4.1 against a 0.4.0 or newer database. Running it against older versions of Titan will not cause an immediate exception but undetermined behavior down the road.
Titan’s tested version of HBase has been updated from 0.94.7 in Titan 0.4.0 to 0.94.12 in Titan 0.4.1. These HBase versions are binary compatible. According to HBase’s versioning policy, code and data using .7 should interoperate seamlessly with .12. Furthermore, HBase supports rolling upgrades between these versions. HBase’s changelog lists all of the intervening releases as bugfix releases.
Titan 0.4.0 is incompatible with previous releases. No upgrade process available from previous versions of Titan yet. Please check the mailing list for updates on the upgrade process.
When upgrading code from previous versions of Titan, please note, that the TypeMaker API has changed significantly. Use 'makeKey' and 'makeLabel' to define keys and labels respectively instead of 'makeType'. Those methods expect the name of the type as the argument. Furthermore, primaryKey() has been renamed to sortKey() and uniqueness has been renamed:
-
For Titan keys:
-
unique()replacesunique(Direction.IN) -
single()replacesunique(Direction.OUT) -
use
list()to allow multiple properties for the key
-
-
For Titan labels:
-
oneToMany()replacesunique(Direction.IN) -
manyToOne()replacesunique(Direction.OUT) -
oneToOne()replacesunique(Direction.IN).unique(Direction.OUT)
-
Rexster Server configuration and dependencies have been moved into the new module titan-rexster and are no longer part of titan-core
The interface has been extended by method to a) verify that the provided value is valid and b) automatically convert the value if possible. These methods are required which means that any implementation of AttributeSerializer must be updated.
Titan 0.3.2 is compatible with 0.3.0 and no special upgrade is necessary unless Elasticsearch is used. If you are using Elasticsearch, please see the notes on upgrading to 0.3.1 from 0.3.0 below.
Titan 0.3.1 is compatible with 0.3.0 and no special upgrade is necessary unless Elasticsearch is used as a storage backend. Titan 0.3.1 uses Elasticsearch 0.90.0 whereas Titan 0.3.0 uses Elasticsearch 0.20.6.
If you are using Elasticsearch, please follow the upgrade instructions for Elasticsearch which are summarized as follows: * Elasticsearch 0.90.0 is the first stable release based on Lucene 4. We recommend testing the upgrade before doing it in production. * Upgrading from 0.20.x requires a full cluster restart. * In order to be able to downgrade, stop indexing new data, issue a flush request, do the upgrade and only enable indexing of new data once you are certain that you no longer need to downgrade. Once new data has been indexed, downgrading is no longer possible. To be extra safe, back up your data before upgrading.
Note, that these instructions apply to the Elasticsearch cluster only and not the Titan cluster or the Titan storage cluster.
Titan 0.3.0 is incompatible with prior versions of Titan. The upgrade process is in development and not yet available.
When upgrading to Titan 0.3.0, please note the following interface changes:
-
In
TypeMaker,functional()has been replaced byunique(Direction.OUT). Likewise,functional(boolean)has been replaced byunique(Direction.OUT, UniquenessConsistency), where the argumenttruecorresponds toUniquenessConsistency.LOCKandfalsecorresponds toUniquenessConsistency.NO_LOCK. -
In
TypeMaker,unique()for property keys has been replaced byunique(Direction.IN). -
In
TypeMaker,indexed()takes additional arguments because Titan now supports vertex and edge indexing. Useindexed(Class<? extends Element>)to create a standard index for the key. Useindexed(String, Class<? extends Element>)to create an external index for the key. -
In
TypeMaker,simple()is no longer available. Simply remove it. -
In
TitanFactory,openInMemoryGraph()is no longer available. Instead, useopen(Configuration)where the configuration setsstorage.backend=inmemory. -
In
AttributeSerializer,writeObjectData()now usesDataOutputto write elements instead ofByteBuffer. A simple replace in any particular implementation ofAttributeSerializershould do the trick.
No special upgrade necessary. Since 0.2.1 has upgraded to Blueprints 2.3.0, there are some incompatible interface changes. In particular, Graph.startTransaction() has been renamed to Graph.newTransaction(). Please refer to the Blueprints documentation for more information.
-
Shut down all running instances of Titan. If the storage backend is Cassandra or HBase, do not shut down the respective storage backend but leave it running. So, only terminate the Titan processes.
-
Create a backup of the storage backend. For BerkeleyDB, simply archive the contents of the storage directory. For Cassandra and HBase, follow the directions for the respective backup functionalities. Store the backup in a secure place.
-
Download and unzip Titan 0.2.0 on the (or one of the) machines that has been running Titan previously.
-
Execute the upgrade010to020.sh/bat script in the bin directory of Titan 0.2.0 with the file name of the Titan configuration file (i.e. the argument passed into
TitanFactory.open()) as the only argument. Follow the instructions. If asked to confirm the id block size, please ensure that the displayed value matches your configuration. If you did not configure this value, simply enter yes. Ensure that the script completes successfully. -
Install Titan 0.2.0 on all machines. Start Titan 0.2.0. Only use the 0.2.0 version of Titan from this point on.