You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@paimon.apache.org by lz...@apache.org on 2023/04/25 02:26:14 UTC
[incubator-paimon] 07/17: [doc] Improve Java API documentation (#979)
This is an automated email from the ASF dual-hosted git repository.
lzljs3620320 pushed a commit to branch release-0.4
in repository https://gitbox.apache.org/repos/asf/incubator-paimon.git
commit 81766b97c30827b65425e27ff7348be7970f00de
Author: s7monk <34...@users.noreply.github.com>
AuthorDate: Sun Apr 23 12:08:27 2023 +0800
[doc] Improve Java API documentation (#979)
---
docs/content/api/java-api.md | 259 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 259 insertions(+)
diff --git a/docs/content/api/java-api.md b/docs/content/api/java-api.md
index 1450b8035..44ffa686a 100644
--- a/docs/content/api/java-api.md
+++ b/docs/content/api/java-api.md
@@ -76,6 +76,82 @@ public class CreateCatalog {
}
```
+## Create Database
+
+You can use the catalog to create databases. The created databases are persistence in the file system.
+
+```java
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.fs.Path;
+
+public class CreateDatabase {
+
+ public static void main(String[] args) {
+ try {
+ catalog.createDatabase("my_db", false);
+ } catch (Catalog.DatabaseAlreadyExistException e) {
+ // do something
+ }
+ }
+}
+```
+
+## Determine Whether Database Exists
+
+You can use the catalog to determine whether the database exists
+
+```java
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.fs.Path;
+
+public class DatabaseExists {
+
+ public static void main(String[] args) {
+ boolean exists = catalog.databaseExists("my_db");
+ }
+}
+```
+
+## List Databases
+
+You can use the catalog to list databases.
+
+```java
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.fs.Path;
+
+public class ListDatabases {
+
+ public static void main(String[] args) {
+ List<String> databases = catalog.listDatabases();
+ }
+}
+```
+
+## Drop Database
+
+You can use the catalog to drop databases.
+
+```java
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.catalog.CatalogContext;
+import org.apache.paimon.catalog.CatalogFactory;
+import org.apache.paimon.fs.Path;
+
+public class DropDatabase {
+
+ public static void main(String[] args) {
+ try {
+ catalog.dropDatabase("my_db", false, true);
+ } catch (Catalog.DatabaseNotEmptyException e) {
+ // do something
+ } catch (Catalog.DatabaseNotExistException e) {
+ // do something
+ }
+ }
+}
+```
+
## Create Table
You can use the catalog to create tables. The created tables are persistence in the file system.
@@ -132,6 +208,189 @@ public class GetTable {
}
```
+## Determine Whether Table Exists
+
+You can use the catalog to determine whether the table exists
+
+```java
+import org.apache.paimon.fs.Path;
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.catalog.Identifier;
+
+public class TableExists {
+
+ public static void main(String[] args) {
+ Identifier identifier = Identifier.create("my_db", "my_table");
+ boolean exists = catalog.tableExists(identifier);
+ }
+}
+```
+
+## List Tables
+
+You can use the catalog to list tables.
+
+```java
+import org.apache.paimon.fs.Path;
+import org.apache.paimon.catalog.Catalog;
+
+public class ListTables {
+
+ public static void main(String[] args) {
+ try {
+ catalog.listTables("my_db");
+ } catch (Catalog.DatabaseNotExistException e) {
+ // do something
+ }
+ }
+}
+```
+
+## Drop Table
+
+You can use the catalog to drop table.
+
+```java
+import org.apache.paimon.fs.Path;
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.catalog.Identifier;
+
+public class DropTable {
+
+ public static void main(String[] args) {
+ Identifier identifier = Identifier.create("my_db", "my_table");
+ try {
+ catalog.dropTable(identifier, false);
+ } catch (Catalog.TableNotExistException e) {
+ // do something
+ }
+ }
+}
+```
+
+## Rename Table
+
+You can use the catalog to rename a table.
+
+```java
+import org.apache.paimon.fs.Path;
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.catalog.Identifier;
+
+public class RenameTable {
+
+ public static void main(String[] args) {
+ Identifier fromTableIdentifier = Identifier.create("my_db", "my_table");
+ Identifier toTableIdentifier = Identifier.create("my_db", "test_table");
+ try {
+ catalog.renameTable(fromTableIdentifier, toTableIdentifier, false);
+ } catch (Catalog.TableAlreadyExistException e) {
+ // do something
+ } catch (Catalog.TableNotExistException e) {
+ // do something
+ }
+ }
+}
+```
+
+## Alter Table
+
+You can use the catalog to alter a table, but you need to pay attention to the following points.
+
+- Add column cannot specify NOT NULL.
+- Cannot update partition column type in the table.
+- Cannot change nullability of primary key.
+- If the type of the column is nested row type, update the column type is not supported.
+- Update column to nested row type is not supported.
+
+```java
+import org.apache.paimon.fs.Path;
+import org.apache.paimon.catalog.Catalog;
+import org.apache.paimon.catalog.Identifier;
+import org.apache.paimon.schema.SchemaChange;
+import org.apache.paimon.table.Table;
+import org.apache.paimon.types.DataField;
+import org.apache.paimon.types.DataTypes;
+import com.google.common.collect.Lists;
+import java.util.Arrays;
+
+public class AlterTable {
+
+ public static void main(String[] args) {
+ Identifier identifier = Identifier.create("my_db", "my_table");
+
+ Map<String,String> options = new HashMap<>();
+ options.put("bucket", "4");
+ options.put("compaction.max.file-num", "40");
+
+ catalog.createTable(
+ identifier,
+ new Schema(
+ Lists.newArrayList(
+ new DataField(0, "col1", DataTypes.STRING(), "field1"),
+ new DataField(1, "col2", DataTypes.STRING(), "field2"),
+ new DataField(2, "col3", DataTypes.STRING(), "field3"),
+ new DataField(3, "col4", DataTypes.BIGINT(), "field4"),
+ new DataField(
+ 4,
+ "col5",
+ DataTypes.ROW(
+ new DataField(5, "f1", DataTypes.STRING(), "f1"),
+ new DataField(6, "f2", DataTypes.STRING(), "f2"),
+ new DataField(7, "f3", DataTypes.STRING(), "f3")),
+ "field5"),
+ new DataField(8, "col6", DataTypes.STRING(), "field6")),
+ Lists.newArrayList("col1"), // partition keys
+ Lists.newArrayList("col1", "col2"), //primary key
+ options,
+ "table comment"),
+ false);
+
+ // add option
+ SchemaChange addOption = SchemaChange.setOption("snapshot.time-retained", "2h");
+ // remove option
+ SchemaChange removeOption = SchemaChange.removeOption("compaction.max.file-num");
+ // add column
+ SchemaChange addColumn = SchemaChange.addColumn("col1_after", DataTypes.STRING());
+ // add a column after col1
+ SchemaChange.Move after = SchemaChange.Move.after("col1_after", "col1");
+ SchemaChange addColumnAfterField =
+ SchemaChange.addColumn("col7", DataTypes.STRING(), "", after);
+ // rename column
+ SchemaChange renameColumn = SchemaChange.renameColumn("col3", "col3_new_name");
+ // drop column
+ SchemaChange dropColumn = SchemaChange.dropColumn("col6");
+ // update column comment
+ SchemaChange updateColumnComment = SchemaChange.updateColumnComment(new String[]{"col4"}, "col4 field");
+ // update nested column comment
+ SchemaChange updateNestedColumnComment =
+ SchemaChange.updateColumnComment(new String[]{"col5", "f1"}, "col5 f1 field");
+ // update column type
+ SchemaChange updateColumnType = SchemaChange.updateColumnType("col4", DataTypes.DOUBLE());
+ // update column position, you need to pass in a parameter of type Move
+ SchemaChange updateColumnPosition = SchemaChange.updateColumnPosition(SchemaChange.Move.first("col4"));
+ // update column nullability
+ SchemaChange updateColumnNullability = SchemaChange.updateColumnNullability(new String[]{"col4"}, false);
+ // update nested column nullability
+ SchemaChange updateNestedColumnNullability =
+ SchemaChange.updateColumnNullability(new String[]{"col5", "f2"}, false);
+ SchemaChange[] schemaChanges = new SchemaChange[] {addOption, removeOption, addColumn, addColumnAfterField,
+ renameColumn, dropColumn, updateColumnComment, updateNestedColumnComment, updateColumnType, updateColumnPosition,
+ updateColumnNullability, updateNestedColumnNullability};
+
+ try {
+ catalog.alterTable(identifier, Arrays.asList(schemaChanges), false);
+ } catch (Catalog.TableNotExistException e) {
+ // do something
+ } catch (Catalog.TableAlreadyExistException e) {
+ // do something
+ } catch (Catalog.DatabaseNotExistException e) {
+ // do something
+ }
+ }
+}
+```
+
Table metadata:
- `name` return a name string to identify this table.