com.datastrato.gravitino.file.FilesetCatalog Maven / Gradle / Ivy
Show all versions of api Show documentation
/*
* Copyright 2024 Datastrato Pvt Ltd.
* This software is licensed under the Apache License version 2.
*/
package com.datastrato.gravitino.file;
import com.datastrato.gravitino.NameIdentifier;
import com.datastrato.gravitino.Namespace;
import com.datastrato.gravitino.annotation.Evolving;
import com.datastrato.gravitino.exceptions.FilesetAlreadyExistsException;
import com.datastrato.gravitino.exceptions.NoSuchFilesetException;
import com.datastrato.gravitino.exceptions.NoSuchSchemaException;
import com.datastrato.gravitino.file.FilesetChange.RenameFileset;
import java.util.Map;
/**
* The FilesetCatalog interface defines the public API for managing fileset objects in a schema. If
* the catalog implementation supports fileset objects, it should implement this interface.
*/
@Evolving
public interface FilesetCatalog {
/**
* List the filesets in a schema namespace from the catalog.
*
* @param namespace A schema namespace.
* @return An array of fileset identifiers in the namespace.
* @throws NoSuchSchemaException If the schema does not exist.
*/
NameIdentifier[] listFilesets(Namespace namespace) throws NoSuchSchemaException;
/**
* Load fileset metadata by {@link NameIdentifier} from the catalog.
*
* @param ident A fileset identifier.
* @return The fileset metadata.
* @throws NoSuchFilesetException If the fileset does not exist.
*/
Fileset loadFileset(NameIdentifier ident) throws NoSuchFilesetException;
/**
* Check if a fileset exists using an {@link NameIdentifier} from the catalog.
*
* @param ident A fileset identifier.
* @return true If the fileset exists, false otherwise.
*/
default boolean filesetExists(NameIdentifier ident) {
try {
loadFileset(ident);
return true;
} catch (NoSuchFilesetException e) {
return false;
}
}
/**
* Create a fileset metadata in the catalog.
*
* If the type of the fileset object is "MANAGED", the underlying storageLocation can be null,
* and Gravitino will manage the storage location based on the location of the schema.
*
*
If the type of the fileset object is "EXTERNAL", the underlying storageLocation must be set.
*
* @param ident A fileset identifier.
* @param comment The comment of the fileset.
* @param type The type of the fileset.
* @param storageLocation The storage location of the fileset.
* @param properties The properties of the fileset.
* @return The created fileset metadata
* @throws NoSuchSchemaException If the schema does not exist.
* @throws FilesetAlreadyExistsException If the fileset already exists.
*/
Fileset createFileset(
NameIdentifier ident,
String comment,
Fileset.Type type,
String storageLocation,
Map properties)
throws NoSuchSchemaException, FilesetAlreadyExistsException;
/**
* Apply the {@link FilesetChange change} to a fileset in the catalog.
*
* Implementation may reject the change. If any change is rejected, no changes should be
* applied to the fileset.
*
*
The {@link RenameFileset} change will only update the fileset name, the underlying storage
* location for managed fileset will not be renamed.
*
* @param ident A fileset identifier.
* @param changes The changes to apply to the fileset.
* @return The altered fileset metadata.
* @throws NoSuchFilesetException If the fileset does not exist.
* @throws IllegalArgumentException If the change is rejected by the implementation.
*/
Fileset alterFileset(NameIdentifier ident, FilesetChange... changes)
throws NoSuchFilesetException, IllegalArgumentException;
/**
* Drop a fileset from the catalog.
*
*
The underlying files will be deleted if this fileset type is managed, otherwise, only the
* metadata will be dropped.
*
* @param ident A fileset identifier.
* @return true If the fileset is dropped, false the fileset did not exist.
*/
boolean dropFileset(NameIdentifier ident);
}