Skip to main content
Version: 0.5.1

Gravitino configuration


Gravitino supports several configurations:

  1. Gravitino server configuration: Used to start up the Gravitino server.
  2. Gravitino catalog properties configuration: Used to make default values for different catalogs.
  3. Some other configurations: Includes HDFS and other configurations.

Gravitino server configurations

You can customize the Gravitino server by editing the configuration file gravitino.conf in the conf directory. The default values are sufficient for most use cases. We strongly recommend that you read the following sections to understand the configuration file so you can change the default values to suit your specific situation and usage scenario.

The gravitino.conf file lists the configuration items in the following table. It groups those items into the following categories:

Gravitino HTTP Server configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.server.webserver.hostThe host of the Gravitino server.
gravitino.server.webserver.httpPortThe port on which the Gravitino server listens for incoming connections.8090No0.1.0
gravitino.server.webserver.minThreadsThe minimum number of threads in the thread pool used by the Jetty webserver. minThreads is 8 if the value is less than 8.Math.max(Math.min(Runtime.getRuntime().availableProcessors() * 2, 100), 8)No0.2.0
gravitino.server.webserver.maxThreadsThe maximum number of threads in the thread pool used by the Jetty webserver. maxThreads is 8 if the value is less than 8, and maxThreads must be great or equal to minThreads.Math.max(Runtime.getRuntime().availableProcessors() * 4, 400)No0.1.0
gravitino.server.webserver.threadPoolWorkQueueSizeThe size of the queue in the thread pool used by the Jetty webserver.100No0.1.0
gravitino.server.webserver.stopTimeoutTime in milliseconds to gracefully shut down the Jetty webserver, for more, please see org.eclipse.jetty.server.Server#setStopTimeout.30000No0.2.0
gravitino.server.webserver.idleTimeoutThe timeout in milliseconds of idle connections.30000No0.2.0
gravitino.server.webserver.requestHeaderSizeMaximum size of HTTP requests.131072No0.1.0
gravitino.server.webserver.responseHeaderSizeMaximum size of HTTP responses.131072No0.1.0
gravitino.server.shutdown.timeoutTime in milliseconds to gracefully shut down of the Gravitino webserver.3000No0.2.0
gravitino.server.webserver.customFiltersComma-separated list of filter class names to apply to the API.(none)No0.4.0

The filter in the customFilters should be a standard javax servlet filter. You can also specify filter parameters by setting configuration entries of the form gravitino.server.webserver.<class name of filter>.param.<param name>=<value>.

Storage configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.entity.storeWhich storage implementation to use. Key-value pair storage and relational storage are currently supported, the default value is kv, and the optional value is relational.kvNo0.1.0 implementation of KV storage. RocksDB storage is currently supported, and the implementation is RocksDBKvBackend.RocksDBKvBackendNo0.1.0 storage path for RocksDB storage implementation. It supports both absolute and relative path, if the value is a relative path, the final path is ${GRAVITINO_HOME}/${PATH_YOU_HAVA_SET}, default value is ${GRAVITINO_HOME}/data/rocksdb${GRAVITINO_HOME}/data/rocksdbNo0.1.0
graivitino.entity.serdeThe serialization/deserialization class used to support entity storage. `proto' is currently supported.protoNo0.1.0 maximum skew time of transactions in milliseconds.2000No0.3.0 is deprecated since Gravitino 0.5.0. Please use instead.604800000(7 days)No0.3.0 maximum time in milliseconds that deleted and old-version data is kept. Set to at least 10 minutes and no longer than 30 days.604800000(7 days)No0.5.0 Count of versions allowed to be retained, including the current version, used to delete old versions data. Set to at least 1 and no greater than 10.1No0.5.0 implementation of Relational storage. MySQL is currently supported, and the implementation is JDBCBackend.JDBCBackendNo0.5.0 database url that the JDBCBackend needs to connect to. If you use MySQL, you should firstly initialize the database tables yourself by executing the ddl scripts in the ${GRAVITINO_HOME}/scripts/mysql/ directory.(none)Yes if you use JDBCBackend0.5.0 jdbc driver name that the JDBCBackend needs to use. You should place the driver Jar package in the ${GRAVITINO_HOME}/libs/ directory.(none)Yes if you use JDBCBackend0.5.0 username that the JDBCBackend needs to use when connecting the database. It is required for MySQL.(none)Yes if you use JDBCBackend0.5.0 password that the JDBCBackend needs to use when connecting the database. It is required for MySQL.(none)Yes if you use JDBCBackend0.5.0

We strongly recommend that you change the default value of, as it's under the deployment directory and future version upgrades may remove it.

Tree lock configuration

Gravitino server uses tree lock to ensure the consistency of the data. The tree lock is a memory lock (Currently, Gravitino only supports in memory lock) that can be used to ensure the consistency of the data in Gravitino server. The configuration items are as follows:

Configuration itemDescriptionDefault valueRequiredSince Version
gravitino.lock.maxNodesThe maximum number of tree lock nodes to keep in memory100000No0.5.0
gravitino.lock.minNodesThe minimum number of tree lock nodes to keep in memory1000No0.5.0
gravitino.lock.cleanIntervalInSecsThe interval in seconds to clean up the stale tree lock nodes60No0.5.0

Catalog configuration

Configuration itemDescriptionDefault valueRequiredSince version
gravitino.catalog.cache.evictionIntervalMsThe interval in milliseconds to evict the catalog cache; default 3600000ms(1h).3600000No0.1.0
gravitino.catalog.classloader.isolatedWhether to use an isolated classloader for catalog. If true, an isolated classloader loads all catalog-related libraries and configurations, not the AppClassLoader. The default value is true.trueNo0.1.0

Auxiliary service configuration

Configuration itemDescriptionDefault valueSince Version
gravitino.auxService.names The auxiliary service name of the Gravitino Iceberg REST server. Use iceberg-rest for the Gravitino Iceberg REST server.(none)0.2.0

Refer to Iceberg REST catalog service for configuration details.

Event listener configuration

Gravitino provides event listener mechanism to allow users to capture the events which are provided by Gravitino server to integrate some custom operations.

To leverage the event listener, you must implement the EventListenerPlugin interface and place the JAR file in the classpath of the Gravitino server. Then, add configurations to gravitino.conf to enable the event listener.

Property nameDescriptionDefault valueRequiredSince Version
gravitino.eventListener.namesThe name of the event listener, For multiple listeners, separate names with a comma, like "audit,sync"(none)Yes0.5.0
gravitino.eventListener.{name}.classNameThe class name of the event listener, replace {name} with the actual listener name.(none)Yes0.5.0
gravitino.eventListener.{name}.{key}Custom properties that will be passed to the event listener plugin.(none)Yes0.5.0


Gravitino triggers a specific event upon the completion of the operation, with varying events being generated for different operations.

operation typeevent
table operationCreateTableEvent, AlterTableEvent, DropTableEvent, LoadTableEvent, ListTableEvent, PurgeTableFailureEvent, CreateTableFailureEvent, AlterTableFailureEvent, DropTableFailureEvent, LoadTableFailureEvent, ListTableFailureEvent, PurgeTableFailureEvent
fileset operationCreateFileSetEvent, AlterFileSetEvent, DropFileSetEvent, LoadFileSetEvent, ListFileSetEvent, CreateFileSetFailureEvent, AlterFileSetFailureEvent, DropFileSetFailureEvent, LoadFileSetFailureEvent, ListFileSetFailureEvent
topic operationCreateTopicEvent, AlterTopicEvent, DropTopicEvent, LoadTopicEvent, ListTopicEvent, CreateTopicFailureEvent, AlterTopicFailureEvent, DropTopicFailureEvent, LoadTopicFailureEvent, ListTopicFailureEvent
schema operationCreateSchemaEvent, AlterSchemaEvent, DropSchemaEvent, LoadSchemaEvent, ListSchemaEvent, CreateSchemaFailureEvent, AlterSchemaFailureEvent, DropSchemaFailureEvent, LoadSchemaFailureEvent, ListSchemaFailureEvent
catalog operationCreateCatalogEvent, AlterCatalogEvent, DropCatalogEvent, LoadCatalogEvent, ListCatalogEvent, CreateCatalogFailureEvent, AlterCatalogFailureEvent, DropCatalogFailureEvent, LoadCatalogFailureEvent, ListCatalogFailureEvent
metalake operationCreateMetalakeEvent, AlterMetalakeEvent, DropMetalakeEvent, LoadMetalakeEvent, ListMetalakeEvent, CreateMetalakeFailureEvent, AlterMetalakeFailureEvent, DropMetalakeFailureEvent, LoadMetalakeFailureEvent, ListMetalakeFailureEvent

Event listener plugin

The EventListenerPlugin defines an interface for event listeners that manage the lifecycle and state of a plugin. This includes handling its initialization, startup, and shutdown processes, as well as handing events triggered by various operations.

The plugin provides several operational modes for how to process event, supporting both synchronous and asynchronous processing approaches.

  • SYNC: Events are processed synchronously, immediately following the associated operation. This mode ensures events are processed before the operation's result is returned to the client, but it may delay the main process if event processing takes too long.

  • ASYNC_SHARED: This mode employs a shared queue and dispatcher for asynchronous event processing. It prevents the main process from being blocked, though there's a risk events might be dropped if not promptly consumed. Sharing a dispatcher can lead to poor isolation in case of slow listeners.

  • ASYNC_ISOLATED: Events are processed asynchronously, with each listener having its own dedicated queue and dispatcher thread. This approach offers better isolation but at the expense of multiple queues and dispatchers.

For more details, please refer to the definition of the plugin.

Security configuration

Refer to security for HTTPS and authentication configurations.

Metrics configuration

Property nameDescriptionDefault valueRequiredSince Version
gravitino.metrics.timeSlidingWindowSecsThe seconds of Gravitino metrics time sliding window60No0.5.1

Gravitino catalog properties configuration

There are three types of catalog properties:

  1. Gravitino defined properties: Gravitino defines these properties as the necessary configurations for the catalog to work properly.
  2. Properties with the gravitino.bypass. prefix: These properties are not managed by Gravitino and pass directly to the underlying system for advanced usage.
  3. Other properties: Gravitino doesn't leverage these properties, just store them. Users can use them for their own purposes.

Catalog properties are either defined in catalog configuration files as default values or specified as properties explicitly when creating a catalog.


The catalog properties explicitly specified in the properties field take precedence over the default values in the catalog configuration file.

These rules only apply to the catalog properties and don't affect the schema or table properties.

Below is a list of catalog properties that will be used by all Gravitino catalogs:

Configuration itemDescriptionDefault valueRequiredSince version
packageThe path of the catalog package, Gravitino leverages this path to load the related catalog libs and configurations. The package should consist two folders, conf (for catalog related configurations) and libs (for catalog related dependencies/jars)(none)No0.5.0

The following table lists the catalog specific properties and their default paths:

catalog providercatalog propertiescatalog properties configuration file path
hiveHive catalog propertiescatalogs/hive/conf/hive.conf
lakehouse-icebergLakehouse Iceberg catalog propertiescatalogs/lakehouse-iceberg/conf/lakehouse-iceberg.conf
jdbc-mysqlMySQL catalog propertiescatalogs/jdbc-mysql/conf/jdbc-mysql.conf
jdbc-postgresqlPostgreSQL catalog propertiescatalogs/jdbc-postgresql/conf/jdbc-postgresql.conf
jdbc-dorisDoris catalog propertiescatalogs/jdbc-doris/conf/jdbc-doris.conf

The Gravitino server automatically adds the catalog properties configuration directory to classpath.

Some other configurations

You could put HDFS configuration file to the catalog properties configuration dir, like catalogs/lakehouse-iceberg/conf/.

How to set up runtime environment variables

The Gravitino server lets you set up runtime environment variables by editing the file, located in the conf directory.

How to access Apache Hadoop

Currently, due to the absence of a comprehensive user permission system, Gravitino can only use a single username for Apache Hadoop access. Ensure that the user starting the Gravitino server has Hadoop (HDFS, YARN, etc.) access permissions; otherwise, you may encounter a Permission denied error. There are two ways to resolve this error:

  • Grant Gravitino startup user permissions in Hadoop
  • Specify the authorized Hadoop username in the environment variables HADOOP_USER_NAME before starting the Gravitino server.