feat: add apache gravitino lance namespace implementations

[shaofengshi]

Apache Gravitino v1.1.0 has released its implementation for Lance Rest service, see https://gravitino.apache.org/docs/1.1.0/lance-rest-service

Now I add the implementation for user to easily adopt that. This pr includes:

• python implementation
• java implementation
• unit test case and integration test
• example code
• document updation.

The gravitino_example.py can be directly run after start a Gravitino docker container in local.

[github-actions]

ACTION NEEDED
Lance follows the Conventional Commits specification for release automation.

The PR title and description are used as the merge commit message. Please update your PR title and description to match the specification.

For details on the error please inspect the "PR Title Check" action.

[shaofengshi]

[shaofengshi]

Can somebody review my PR? Thanks!

[jackye1995]

I am a bit confused, I thought it could directly work with the RestNamespace which is in core lance repo? Why do we need this implementation?

[shaofengshi]

I am a bit confused, I thought it could directly work with the RestNamespace which is in core lance repo? Why do we need this implementation?

Good quesiton! Although Gravitino implements the Lance REST API spec, its specific conventions, URL structure, hierarchy rules, and ecosystem integration requirements make a dedicated implementation more maintainable, user-friendly, and robust than trying to use a generic REST client.

For example: Gravitino enforces a strict three-level hierarchy (catalog → schema → table) that requires validation:

• Namespaces can only be 1 or 2 levels deep
• Tables must be exactly 3 levels
• The implementation validates these constraints and provides clear error messages

This is why we add this: make user easier to get started with it. Hope this helps.

[jackye1995]

Sorry for the late reply, was a bit sick past few days.

I checked in details about this implementation compared to the one in lance main repo. Looks like there are 2 key differences:

1. the enforcement of 3 levels for table (2 levels for namespace)
2. the prefix /lance/v1 instead of just /v1.

I think we probably want to handle them differently.

For 1, there has been multiple discussions about this in other contexts, which all point to the same solution: what we should do is a 3LevelNamespaceAdapter that can adapt any namespace implementation to exactly 3 levels, and that can be a part of lance-namespace offered as core utility for java and python. And in that adapter, it can be defined that accessing non-3 level tables is not allowed.

For 2, I think that is totally reasonable feature to add directly in RestNamespace so that there is a bath path after the endpoint. It is a part of the spec (https://github.com/lance-format/lance-namespace/blob/main/docs/src/rest.yaml#L32), we probably just did not implement it.

What do you think?

[shaofengshi]

Hi Jack, I agree with you; If Lance namespace implementation can support above features natively, that would be great for other implementations! Then what's your suggestion for this PR? Could we merge it first and update later when Lance namespace implementation get updated? Thanks!

[jackye1995]

Looks like for 2, it is already supported today:

  Map<String, String> properties = new HashMap<>();
  // Base path "/my-prefix" sits between host and /v1
  properties.put("uri", "https://api.example.com/my-prefix");
  properties.put("delimiter", ".");
  properties.put("header.Authorization", "Bearer my-token");

  RestNamespace namespace = new RestNamespace();
  namespace.initialize(properties, allocator);

For 1, would you be interested in the implementation?

But overall I think we should not merge this, since the goal of doing a REST namespace server is that it uses the Rest namespace that is maintained in the core lance repo that gets all the first-class integration and testing. Doing this defeats that purpose.

[shaofengshi]

I understand. Sure, for issue 1, I can work on it; But I'm not sure which repo should it be contribute to, the lance-format/lance-namespace one or this one; if you already have some decisions, please share to me, thank you! @jackye1995

[shaofengshi]

Jack, for the issue 1, new PR is created, please take a look: #31 @jackye1995