UnityCatalogServer — Localhost Reference Server¶

UnityCatalogServer is Unity Catalog's Localhost Reference Server.

UnityCatalogServer can be started on command line to handle REST API requests at the port.

❯ ./bin/start-uc-server --help
usage: bin/start-uc-server
 -h,--help         Print help message.
 -p,--port <arg>   Port number to run the server on. Default is 8080.
 -v,--version      Display the version of the Unity Catalog server

UnityCatalogServer starts Armeria documentation service at http://localhost:8081/docs and the other Unity Catalog API services.

Metastore¶

UnityCatalogServer runs with a single metastore only that can be created unless available already.

The summary of the single metastore is available through MetastoreService at /api/2.1/unity-catalog/ URL.

Configuration Files¶

UnityCatalogServer uses the following configuration files:

• etc/conf/server.log4j2.properties
• etc/conf/server.properties

Port¶

UnityCatalogServer takes a port number when created.

Unless specified on command-line using -p,--port <arg> option, UnityCatalogServer defaults to 8080 or the closest one available.

Creating Instance¶

UnityCatalogServer takes the following to be created:

• Port

While being created, UnityCatalogServer builds the Server:

1. Handle HTTP requests at the given port
2. Bind the Armeria documentation service (Armeria) under /docs URL
3. Register the API services

UnityCatalogServer is created when:

• UnityCatalogServer command-line utility is started

Server¶

UnityCatalogServer creates a Server (Armeria) when created.

SecurityContext¶

UnityCatalogServer creates a SecurityContext when created as follows:

This SecurityContext is used to create an AuthService.

Register API Services¶

void addServices(
  ServerBuilder sb)

addServices initializes an authorizer based on server.authorization configuration property. When enabled (enable), addServices creates a JCasbinAuthorizer and initializes the admin user. Otherwise, addServices creates an AllowingAuthorizer.

addServices creates and registers Unity Catalog API services at the /api/2.1/unity-catalog/ base path.

With server.authorization configuration property enabled, addServices prints out the following INFO message to the logs:

Authorization enabled.

addServices registers HTTP service decorators.

Launch UnityCatalogServer¶

void main(
  String[] args)

main starts probing for the available port from 8081 or the first argument specified on command line.

main creates a UnityCatalogServer.

main requests the UnityCatalogServer to print out the welcome ASCII art message.

main requests the UnityCatalogServer to start.

main creates a URLTranscoderVerticle on the following ports:

main deploys the URLTranscoderVerticle on a non-clustered Vert.x instance.

Start Server¶

void start()

start prints out the following INFO message to the logs:

Starting server...

start requests the MetastoreRepository to initMetastoreIfNeeded.

start requests this Server to start and listen to the defined ports.

start waits until this Server is fully started up.

start is used when:

• UnityCatalogServer is launched on command line

Logging¶

Enable ALL logging level for io.unitycatalog.server.UnityCatalogServer logger to see what happens inside.

Add the following line to etc/conf/server.log4j2.properties:

logger.UnityCatalogServer.name = io.unitycatalog.server.UnityCatalogServer
logger.UnityCatalogServer.level = all

Refer to Logging.