From 4269ea00371220d86bc082a23f6c08f6ac0eabd8 Mon Sep 17 00:00:00 2001 From: Josh Wong <23216828+josh-wong@users.noreply.github.com> Date: Wed, 6 Aug 2025 18:05:58 +0900 Subject: [PATCH 1/4] Add new doc (tentative publication) --- docs/scalardb-analytics/administration.mdx | 798 ++++++++++++++++++ docs/scalardb-analytics/configuration.mdx | 242 ++++++ .../scalardb-analytics/administration.mdx | 794 +++++++++++++++++ .../scalardb-analytics/configuration.mdx | 241 ++++++ 4 files changed, 2075 insertions(+) create mode 100644 docs/scalardb-analytics/administration.mdx create mode 100644 docs/scalardb-analytics/configuration.mdx create mode 100644 i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/administration.mdx create mode 100644 i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/configuration.mdx diff --git a/docs/scalardb-analytics/administration.mdx b/docs/scalardb-analytics/administration.mdx new file mode 100644 index 00000000..783b4319 --- /dev/null +++ b/docs/scalardb-analytics/administration.mdx @@ -0,0 +1,798 @@ +--- +tags: + - Enterprise Option +displayed_sidebar: docsEnglish +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Manage ScalarDB Analytics + +import WarningLicenseKeyContact from "/src/components/en-us/_warning-license-key-contact.mdx"; + +This guide explains how to set up and manage the ScalarDB Analytics server and its catalogs. The ScalarDB Analytics server is the implementation of the Universal Data Catalog described in the [ScalarDB Analytics Design](design.mdx), providing centralized metadata management for analytical queries across multiple databases. + + + +## Overview + +ScalarDB Analytics provides a universal data catalog that enables unified access to multiple databases through a single interface. Based on the Universal Data Catalog architecture described in the [ScalarDB Analytics Design](design.mdx#universal-data-catalog) documentation, the system consists of two main components: + +1. **ScalarDB Analytics server**: A gRPC-based service that manages: + - **Catalog metadata**: Organizes data sources, namespaces, tables, and columns + - **Data source connections**: Maintains connection information and credentials for external databases + - **License validation**: Verifies enterprise licenses + - **Usage metering**: Tracks resource usage for billing purposes + + The server provides two gRPC endpoints: + - Port 11051: Catalog service for metadata operations + - Port 11052: Metering service for usage tracking + +2. **ScalarDB Analytics CLI**: A command-line tool that communicates with the server to manage catalogs, register data sources, and perform administrative tasks + +## Setup + +Before managing catalogs, you need to set up and configure the ScalarDB Analytics server and CLI. + +### Server setup + +#### Prerequisites: Metadata database + +The server requires a database to store catalog metadata and data source connection information. We refer to this database as the **metadata database** throughout this documentation. ScalarDB Analytics supports the following databases for the metadata database: + +- PostgreSQL +- MySQL +- SQL Server +- Oracle + +Create a database and user with appropriate privileges before starting the server. The specific commands vary by database type. + +#### Server configuration + +Create a server configuration file (e.g., `scalardb-analytics-server.properties`). The following example uses PostgreSQL as the metadata database: + +```properties +# Metadata database configuration (required) +scalar.db.analytics.server.db.url=jdbc:postgresql://localhost:5432/scalardb_analytics +scalar.db.analytics.server.db.username=analytics_user +scalar.db.analytics.server.db.password=your_secure_password + +# gRPC server configuration (optional) +scalar.db.analytics.server.catalog.port=11051 # default +scalar.db.analytics.server.metering.port=11052 # default + +# TLS configuration (optional but recommended for production) +scalar.db.analytics.server.tls.enabled=true +scalar.db.analytics.server.tls.cert_chain_path=/path/to/server.crt +scalar.db.analytics.server.tls.private_key_path=/path/to/server.key + +# License configuration (required) +scalar.db.analytics.server.licensing.license_key= +scalar.db.analytics.server.licensing.license_check_cert_pem= + +# Metering storage configuration (required) +scalar.db.analytics.server.metering.storage.provider=filesystem +scalar.db.analytics.server.metering.storage.path=/var/scalardb-analytics/metering +``` + +For detailed configuration options, see the [Configuration reference](configuration.mdx). + +#### Starting the server + +Start the ScalarDB Analytics server with your configuration: + +```console +docker run -d \ + --name scalardb-analytics-server \ + -p 11051:11051 \ + -p 11052:11052 \ + -v /path/to/scalardb-analytics-server.properties:/scalardb-analytics-server/server.properties \ + ghcr.io/scalar-labs/scalardb-analytics-server: +``` + +Replace `` with the ScalarDB Analytics version you want to use. You can find available versions at the [Docker registry page](https://github.com/scalar-labs/scalardb-analytics/pkgs/container/scalardb-analytics-server). + +The container uses the configuration file at `/scalardb-analytics-server/server.properties` by default. + +The server will perform the following during startup: + +1. Validate the license +2. Connect to the metadata database +3. Start gRPC services on the configured ports +4. Begin accepting client connections + +#### Health checks (optional) + +If you want to verify the server is running properly, you can use grpc-health-probe (included in the Docker container): + +```console +# Check catalog service health +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11051 + +# Check metering service health +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11052 + +# For TLS-enabled servers +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11051 -tls -tls-ca-cert=/path/to/ca.crt +``` + +### CLI setup + +#### Installing the CLI + +The `scalardb-analytics-cli` tool is available as a Docker image: + +```console +# Pull the CLI image +docker pull ghcr.io/scalar-labs/scalardb-analytics-cli: +``` + +Replace `` with the ScalarDB Analytics version you want to use. Available versions can be found at the [Docker registry page](https://github.com/scalar-labs/scalardb-analytics/pkgs/container/scalardb-analytics-cli). + +To run CLI commands, you'll need to mount your configuration file into the container: + +```console +# Example: List catalogs +docker run --rm \ + -v $(pwd)/client.properties:/config/client.properties:ro \ + ghcr.io/scalar-labs/scalardb-analytics-cli: \ + -c /config/client.properties \ + catalog list +``` + +#### Client configuration + +Create a configuration file named `client.properties` in your current directory: + +```properties +# Server connection +scalar.db.analytics.client.server.host=localhost +scalar.db.analytics.client.server.catalog.port=11051 +scalar.db.analytics.client.server.metering.port=11052 + +# TLS/SSL configuration (if enabled on server) +scalar.db.analytics.client.server.tls.enabled=true +scalar.db.analytics.client.server.tls.ca_root_cert_path=/path/to/ca.crt +scalar.db.analytics.client.server.tls.override_authority=analytics.example.com +``` + +For detailed configuration options, see the [Configuration reference](configuration.mdx). + +#### Setting up an alias (optional) + +For convenience, you can create an alias to avoid typing the long Docker command each time: + +```console +alias scalardb-analytics-cli='docker run --rm -v $(pwd)/client.properties:/config/client.properties:ro ghcr.io/scalar-labs/scalardb-analytics-cli: -c /config/client.properties' +``` + +With this alias, you can run commands more simply: + +```console +scalardb-analytics-cli catalog list +``` + +## CLI command reference + +The ScalarDB Analytics CLI uses a hierarchical command structure: + +``` +scalardb-analytics [options] +``` + +Available resources: + +- **catalog**: Top-level containers for organizing data sources +- **data-source**: External databases registered within catalogs +- **namespace**: Database-specific organizational units (auto-discovered) +- **table**: Data structures within namespaces (auto-discovered) + +Note: In all examples below, we assume you're using the Docker alias created earlier. If running Docker commands directly, replace `scalardb-analytics-cli` with the full Docker command. + +### Catalog operations + +```console +# Create a new catalog +scalardb-analytics-cli catalog create --catalog + +# List all catalogs +scalardb-analytics-cli catalog list + +# Show catalog details (by name or ID) +scalardb-analytics-cli catalog describe --catalog +scalardb-analytics-cli catalog describe --catalog-id + +# Delete a catalog (fails if not empty unless --cascade is used) +scalardb-analytics-cli catalog delete --catalog +scalardb-analytics-cli catalog delete --catalog --cascade +``` + +### Data source operations + +```console +# Register a new data source using a JSON definition file +scalardb-analytics-cli data-source register --data-source-json + +# List all data sources in a catalog +scalardb-analytics-cli data-source list --catalog + +# Show data source details (by name or ID) +scalardb-analytics-cli data-source describe --catalog --data-source +scalardb-analytics-cli data-source describe --data-source-id + +# Delete a data source (fails if not empty unless --cascade is used) +scalardb-analytics-cli data-source delete --catalog --data-source +scalardb-analytics-cli data-source delete --catalog --data-source --cascade +``` + +The `register` command requires a JSON definition file. The JSON file format is described in the [Data source configuration](#data-source-configuration) section below. + +### Namespace operations + +```console +# List all namespaces in a data source +scalardb-analytics-cli namespace list --catalog --data-source + +# Show namespace details (by name or ID) +# For nested namespaces, use '.' as a separator (e.g., --namespace parent.child) +scalardb-analytics-cli namespace describe --catalog --data-source --namespace +scalardb-analytics-cli namespace describe --namespace-id +``` + +### Table operations + +```console +# List all tables in a namespace +scalardb-analytics-cli table list --catalog --data-source --namespace + +# Show table schema with all columns (by name or ID) +# For nested namespaces, use '.' as a separator (e.g., --namespace parent.child) +scalardb-analytics-cli table describe --catalog --data-source --namespace --table +scalardb-analytics-cli table describe --table-id +``` + +## Data source configuration + +### Data source JSON format + +Data sources are registered using JSON definition files with the following structure: + +```json +{ + "catalog": "", // The catalog to register the data source in + "name": "", // A unique name for this data source + "type": "", // Database type: postgres, mysql, scalardb, sqlserver, oracle, dynamodb + "provider": { + // Type-specific connection configuration + // Configuration varies by database type + } +} +``` + +The `provider` section contains database-specific connection settings that vary based on the `type` field. + +### Provider configuration by type + +The following sections show the provider configuration for each supported database type: + + + + +#### Configuration + +| Field | Required | Description | Default | +| ------------ | -------- | --------------------------------------- | ------- | +| `configPath` | Yes | Path to the ScalarDB configuration file | - | + +**Example:** + +```json +{ + "catalog": "production", + "name": "scalardb_source", + "type": "scalardb", + "provider": { + "configPath": "/path/to/scalardb.properties" + } +} +``` + + + + +#### Configuration + +| Field | Required | Description | Default | +| ---------- | -------- | --------------------------- | ------- | +| `host` | Yes | PostgreSQL server hostname | - | +| `port` | Yes | Port number | - | +| `username` | Yes | Database user | - | +| `password` | Yes | Database password | - | +| `database` | Yes | Database name to connect to | - | + +**Example:** + +```json +{ + "catalog": "production", + "name": "postgres_customers", + "type": "postgres", + "provider": { + "host": "postgres.example.com", + "port": 5432, + "username": "analytics_user", + "password": "secure_password", + "database": "customers" + } +} +``` + + + + +#### Configuration + +| Field | Required | Description | Default | +| ---------- | -------- | ----------------------------------------------------------------------- | ------- | +| `host` | Yes | MySQL server hostname | - | +| `port` | Yes | Port number | - | +| `username` | Yes | Database user | - | +| `password` | Yes | Database password | - | +| `database` | No | Specific database to import. If omitted, all databases will be imported | - | + +**Example:** + +```json +{ + "catalog": "production", + "name": "mysql_orders", + "type": "mysql", + "provider": { + "host": "mysql.example.com", + "port": 3306, + "username": "analytics_user", + "password": "secure_password", + "database": "orders" // Optional - if omitted, all databases will be imported + } +} +``` + + + + +#### Configuration + +| Field | Required | Description | Default | +| ------------- | -------- | ---------------------- | ------- | +| `host` | Yes | Oracle server hostname | - | +| `port` | Yes | Port number | - | +| `username` | Yes | Database user | - | +| `password` | Yes | Database password | - | +| `serviceName` | Yes | Oracle service name | - | + +**Example:** + +```json +{ + "catalog": "production", + "name": "oracle_warehouse", + "type": "oracle", + "provider": { + "host": "oracle.example.com", + "port": 1521, + "username": "analytics_user", + "password": "secure_password", + "serviceName": "ORCL" + } +} +``` + + + + +#### Configuration + +| Field | Required | Description | Default | +| ---------- | -------- | ------------------------------- | ------- | +| `host` | Yes | SQL Server hostname | - | +| `port` | Yes | Port number | - | +| `username` | Yes | Database user | - | +| `password` | Yes | Database password | - | +| `database` | No | Specific database to connect to | - | +| `secure` | No | Enable encryption | - | + +**Example:** + +```json +{ + "catalog": "production", + "name": "sqlserver_analytics", + "type": "sqlserver", + "provider": { + "host": "sqlserver.example.com", + "port": 1433, + "username": "sa", + "password": "secure_password", + "database": "analytics", // Optional - if specified, only this database will be imported + "secure": true // Optional - enable encryption + } +} +``` + + + + +#### Configuration + +| Field | Required | Description | Default | +| ---------- | -------- | ---------------------------- | ------- | +| `region` | Yes\* | AWS region (e.g., us-east-1) | - | +| `endpoint` | Yes\* | Custom endpoint URL | - | +| `schema` | Yes | Complete schema definition | - | + +\* Either `region` or `endpoint` must be specified (not both). + +Since DynamoDB is schema-less, you must provide a complete schema definition. + +##### Schema structure + +| Field | Required | Description | Default | +| -------------------------------------------------- | -------- | -------------------------------------- | ------- | +| `.schema` | Yes | Complete schema definition | - | +| `.schema.namespaces[]` | Yes | Array of namespace definitions | - | +| `.schema.namespaces[].names[]` | Yes | Array of namespace names (strings) | - | +| `.schema.namespaces[].tables[]` | Yes | Array of table definitions | - | +| `.schema.namespaces[].tables[].name` | Yes | Table name | - | +| `.schema.namespaces[].tables[].columns[]` | Yes | Array of column definitions | - | +| `.schema.namespaces[].tables[].columns[].name` | Yes | Column name | - | +| `.schema.namespaces[].tables[].columns[].type` | Yes | Data type | - | +| `.schema.namespaces[].tables[].columns[].nullable` | No | Whether column can contain null values | true | + +**Example:** + +```json +{ + "catalog": "production", + "name": "dynamodb_events", + "type": "dynamodb", + "provider": { + "region": "us-east-1", + "schema": { + "namespaces": [ + { + "names": ["production"], + "tables": [ + { + "name": "user_events", + "columns": [ + { "name": "user_id", "type": "TEXT", "nullable": false }, + { + "name": "event_time", + "type": "TIMESTAMP", + "nullable": false + }, + { "name": "event_type", "type": "TEXT" }, + { "name": "event_data", "type": "TEXT" } + ] + } + ] + } + ] + } + } +} +``` + + + + +## Catalog metadata reference + +### Catalog structure mappings by data source + +When registering a data source to ScalarDB Analytics, the catalog structure of the data source, that is, namespaces, tables, and columns, are resolved and registered to the universal data catalog. To resolve the catalog structure of the data source, a particular object on the data sources side are mapped to the universal data catalog object. + +#### Catalog-level mappings + +The catalog-level mappings are the mappings of the namespace names, table names, and column names from the data sources to the universal data catalog. To see the catalog-level mappings in each data source, select a data source. + + + + The catalog structure of ScalarDB is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: + + - The ScalarDB namespace is mapped to the namespace. Therefore, the namespace of the ScalarDB data source is always single level, consisting of only the namespace name. + - The ScalarDB table is mapped to the table. + - The ScalarDB column is mapped to the column. + + + + + The catalog structure of PostgreSQL is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: + + - The PostgreSQL schema is mapped to the namespace. Therefore, the namespace of the PostgreSQL data source is always single level, consisting of only the schema name. + - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: + - `information_schema` + - `pg_catalog` + - The PostgreSQL table is mapped to the table. + - The PostgreSQL column is mapped to the column. + + + + The catalog structure of MySQL is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: + + - The MySQL database is mapped to the namespace. Therefore, the namespace of the MySQL data source is always single level, consisting of only the database name. + - Only user-defined databases are mapped to namespaces. The following system databases are ignored: + - `mysql` + - `sys` + - `information_schema` + - `performance_schema` + - The MySQL table is mapped to the table. + - The MySQL column is mapped to the column. + + + + The catalog structure of Oracle is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: + + - The Oracle schema is mapped to the namespace. Therefore, the namespace of the Oracle data source is always single level, consisting of only schema name. + - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: + - `ANONYMOUS` + - `APPQOSSYS` + - `AUDSYS` + - `CTXSYS` + - `DBSNMP` + - `DGPDB_INT` + - `DBSFWUSER` + - `DVF` + - `DVSYS` + - `GGSYS` + - `GSMADMIN_INTERNAL` + - `GSMCATUSER` + - `GSMROOTUSER` + - `GSMUSER` + - `LBACSYS` + - `MDSYS` + - `OJVMSYS` + - `ORDDATA` + - `ORDPLUGINS` + - `ORDSYS` + - `OUTLN` + - `REMOTE_SCHEDULER_AGENT` + - `SI_INFORMTN_SCHEMA` + - `SYS` + - `SYS$UMF` + - `SYSBACKUP` + - `SYSDG` + - `SYSKM` + - `SYSRAC` + - `SYSTEM` + - `WMSYS` + - `XDB` + - `DIP` + - `MDDATA` + - `ORACLE_OCM` + - `XS$NULL` + + + + The catalog structure of SQL Server is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: + + - The SQL Server database and schema are mapped to the namespace together. Therefore, the namespace of the SQL Server data source is always two-level, consisting of the database name and the schema name. + - Only user-defined databases are mapped to namespaces. The following system databases are ignored: + - `sys` + - `guest` + - `INFORMATION_SCHEMA` + - `db_accessadmin` + - `db_backupoperator` + - `db_datareader` + - `db_datawriter` + - `db_ddladmin` + - `db_denydatareader` + - `db_denydatawriter` + - `db_owner` + - `db_securityadmin` + - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: + - `master` + - `model` + - `msdb` + - `tempdb` + - The SQL Server table is mapped to the table. + - The SQL Server column is mapped to the column. + + + + Since DynamoDB is schema-less, you need to specify the catalog structure explicitly when registering a DynamoDB data source by using the following format JSON: + + ```json + { + "namespaces": [ + { + "name": "", + "tables": [ + { + "name": "", + "columns": [ + { + "name": "", + "type": "" + }, + ... + ] + }, + ... + ] + }, + ... + ] + } + ``` + + In the specified JSON, you can use any arbitrary namespace names, but the table names must match the table names in DynamoDB and column name and type must match field names and types in DynamoDB. + + + + +### Data type mappings + +The following sections show how native types from each data source are mapped to ScalarDB Analytics types: + + + + +| **ScalarDB Data Type** | **ScalarDB Analytics Data Type** | +| :--------------------- | :------------------------------- | +| `BOOLEAN` | `BOOLEAN` | +| `INT` | `INT` | +| `BIGINT` | `BIGINT` | +| `FLOAT` | `FLOAT` | +| `DOUBLE` | `DOUBLE` | +| `TEXT` | `TEXT` | +| `BLOB` | `BLOB` | +| `DATE` | `DATE` | +| `TIME` | `TIME` | +| `TIMESTAMP` | `TIMESTAMP` | +| `TIMESTAMPTZ` | `TIMESTAMPTZ` | + + + + +| **PostgreSQL Data Type** | **ScalarDB Analytics Data Type** | +| :---------------------------- | :------------------------------- | +| `integer` | `INT` | +| `bigint` | `BIGINT` | +| `real` | `FLOAT` | +| `double precision` | `DOUBLE` | +| `smallserial` | `SMALLINT` | +| `serial` | `INT` | +| `bigserial` | `BIGINT` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `text` | `TEXT` | +| `bpchar` | `TEXT` | +| `boolean` | `BOOLEAN` | +| `bytea` | `BLOB` | +| `date` | `DATE` | +| `time` | `TIME` | +| `time with time zone` | `TIME` | +| `time without time zone` | `TIME` | +| `timestamp` | `TIMESTAMP` | +| `timestamp with time zone` | `TIMESTAMPTZ` | +| `timestamp without time zone` | `TIMESTAMP` | + + + + +| **MySQL Data Type** | **ScalarDB Analytics Data Type** | +| :------------------- | :------------------------------- | +| `bit` | `BOOLEAN` | +| `bit(1)` | `BOOLEAN` | +| `bit(x)` if _x >= 2_ | `BLOB` | +| `tinyint` | `SMALLINT` | +| `tinyint(1)` | `BOOLEAN` | +| `boolean` | `BOOLEAN` | +| `smallint` | `SMALLINT` | +| `smallint unsigned` | `INT` | +| `mediumint` | `INT` | +| `mediumint unsigned` | `INT` | +| `int` | `INT` | +| `int unsigned` | `BIGINT` | +| `bigint` | `BIGINT` | +| `float` | `FLOAT` | +| `double` | `DOUBLE` | +| `real` | `DOUBLE` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `text` | `TEXT` | +| `binary` | `BLOB` | +| `varbinary` | `BLOB` | +| `blob` | `BLOB` | +| `date` | `DATE` | +| `time` | `TIME` | +| `datetime` | `TIMESTAMP` | +| `timestamp` | `TIMESTAMPTZ` | + + + + +| **Oracle Data Type** | **ScalarDB Analytics Data Type** | +| :------------------------------- | :------------------------------- | +| `NUMBER` if _scale = 0_ | `BIGINT` | +| `NUMBER` if _scale > 0_ | `DOUBLE` | +| `FLOAT` if _precision ≤ 53_ | `DOUBLE` | +| `BINARY_FLOAT` | `FLOAT` | +| `BINARY_DOUBLE` | `DOUBLE` | +| `CHAR` | `TEXT` | +| `NCHAR` | `TEXT` | +| `VARCHAR2` | `TEXT` | +| `NVARCHAR2` | `TEXT` | +| `CLOB` | `TEXT` | +| `NCLOB` | `TEXT` | +| `BLOB` | `BLOB` | +| `BOOLEAN` | `BOOLEAN` | +| `DATE` | `DATE` | +| `TIMESTAMP` | `TIMESTAMPTZ` | +| `TIMESTAMP WITH TIME ZONE` | `TIMESTAMPTZ` | +| `TIMESTAMP WITH LOCAL TIME ZONE` | `TIMESTAMP` | +| `RAW` | `BLOB` | + + + + +| **SQL Server Data Type** | **ScalarDB Analytics Data Type** | +| :----------------------- | :------------------------------- | +| `bit` | `BOOLEAN` | +| `tinyint` | `SMALLINT` | +| `smallint` | `SMALLINT` | +| `int` | `INT` | +| `bigint` | `BIGINT` | +| `real` | `FLOAT` | +| `float` | `DOUBLE` | +| `float(n)` if _n ≤ 24_ | `FLOAT` | +| `float(n)` if _n ≥ 25_ | `DOUBLE` | +| `binary` | `BLOB` | +| `varbinary` | `BLOB` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `nchar` | `TEXT` | +| `nvarchar` | `TEXT` | +| `ntext` | `TEXT` | +| `text` | `TEXT` | +| `date` | `DATE` | +| `time` | `TIME` | +| `datetime` | `TIMESTAMP` | +| `datetime2` | `TIMESTAMP` | +| `smalldatetime` | `TIMESTAMP` | +| `datetimeoffset` | `TIMESTAMPTZ` | + + + + +| **DynamoDB Data Type** | **ScalarDB Analytics Data Type** | +| :--------------------- | :------------------------------- | +| `Number` | `BYTE` | +| `Number` | `SMALLINT` | +| `Number` | `INT` | +| `Number` | `BIGINT` | +| `Number` | `FLOAT` | +| `Number` | `DOUBLE` | +| `Number` | `DECIMAL` | +| `String` | `TEXT` | +| `Binary` | `BLOB` | +| `Boolean` | `BOOLEAN` | + +:::warning + +It is important to ensure that the field values of `Number` types are parsable as a specified data type for ScalarDB Analytics. For example, if a column that corresponds to a `Number`-type field is specified as an `INT` type, its value must be an integer. If the value is not an integer, an error will occur when running a query. + +::: + + + + +## Next steps + +After setting up the ScalarDB Analytics server and managing catalogs: + +1. Configure Spark or other query engines to use your catalogs - see [Configuration Reference](configuration.mdx) +2. Start running analytical queries - see [Run Analytical Queries](run-analytical-queries.mdx) +3. Set up production deployment - see [Deployment Guide](deployment.mdx) diff --git a/docs/scalardb-analytics/configuration.mdx b/docs/scalardb-analytics/configuration.mdx new file mode 100644 index 00000000..04245224 --- /dev/null +++ b/docs/scalardb-analytics/configuration.mdx @@ -0,0 +1,242 @@ +--- +tags: + - Enterprise Option +displayed_sidebar: docsEnglish +--- + +# Configuration reference + +This page provides a comprehensive reference for configuring all components of ScalarDB Analytics. + +## Overview + +ScalarDB Analytics consists of three main components that require configuration: + +1. **ScalarDB Analytics server** - The server that hosts the catalog and metering services +2. **CLI client** - The command-line interface for managing catalogs and data sources +3. **Spark integration** - Configuration for using ScalarDB Analytics with Apache Spark + +## ScalarDB Analytics server configuration + +The server is configured using a standard Java properties file (e.g., `scalardb-analytics-server.properties`) that defines database connections, network settings, licensing, and optional features. + +### Configuration properties + +#### Metadata database configuration + +The server requires a metadata database to store catalog information. + +| Property | Required | Description | Default | Example | +| ---------------------------------------- | -------- | ------------------------------------ | ------- | ----------------------------------------------------- | +| `scalar.db.analytics.server.db.url` | Yes | JDBC URL for the metadata database | - | `jdbc:postgresql://localhost:5432/scalardb_analytics` | +| `scalar.db.analytics.server.db.username` | Yes | Database user for authentication | - | `analytics_user` | +| `scalar.db.analytics.server.db.password` | Yes | Database password for authentication | - | `your_secure_password` | + +#### gRPC server configuration + +Configure the ports for the catalog and metering services. + +| Property | Required | Default | Description | Example | +| ------------------------------------------ | -------- | ------- | ----------------------------- | ------- | +| `scalar.db.analytics.server.catalog.port` | No | `11051` | Port for the catalog service | `11051` | +| `scalar.db.analytics.server.metering.port` | No | `11052` | Port for the metering service | `11052` | + +#### TLS configuration + +Enable TLS/SSL for secure communication. + +| Property | Required | Default | Description | Example | +| ------------------------------------------------- | -------- | ------- | ----------------------------------------- | --------------------- | +| `scalar.db.analytics.server.tls.enabled` | No | `false` | Enable TLS/SSL for gRPC endpoints | `true` | +| `scalar.db.analytics.server.tls.cert_chain_path` | Yes\* | - | Path to the server certificate chain file | `/path/to/server.crt` | +| `scalar.db.analytics.server.tls.private_key_path` | Yes\* | - | Path to the server private key file | `/path/to/server.key` | + +\* Required when `tls.enabled` is `true` + +#### License configuration + +Configure your ScalarDB Analytics license. + +| Property | Required | Description | Default | Example | +| -------------------------------------------------------------- | -------- | ---------------------------------------------- | ------- | ------------------------------ | +| `scalar.db.analytics.server.licensing.license_key` | Yes | Your ScalarDB Analytics license key | - | Contact Scalar for license | +| `scalar.db.analytics.server.licensing.license_check_cert_pem` | Yes\* | License verification certificate as PEM string | - | Contact Scalar for certificate | +| `scalar.db.analytics.server.licensing.license_check_cert_path` | Yes\* | Path to license verification certificate file | - | `/path/to/cert.pem` | + +\* Either `license_check_cert_pem` or `license_check_cert_path` must be specified + +#### Metering storage configuration + +Configure storage for metering data. + +| Property | Required | Default | Description | Example | +| ------------------------------------------------------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------ | +| `scalar.db.analytics.server.metering.storage.provider` | Yes | - | Storage provider for metering data (`filesystem`, `aws-s3`, `azureblob`, `google-cloud-storage`) | `filesystem` | +| `scalar.db.analytics.server.metering.storage.containerName` | No | `metering` | Container/bucket name for cloud storage | `my-metering-bucket` | +| `scalar.db.analytics.server.metering.storage.path` | Yes\* | - | Local directory path (for `filesystem` provider only) | `/var/scalardb-analytics/metering` | +| `scalar.db.analytics.server.metering.storage.accessKeyId` | Yes\*\* | - | Access key ID for cloud storage providers | `AKIAIOSFODNN7EXAMPLE` | +| `scalar.db.analytics.server.metering.storage.secretAccessKey` | Yes\*\* | - | Secret access key for cloud storage providers | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` | +| `scalar.db.analytics.server.metering.storage.prefix` | No | - | Optional prefix for all storage paths | `production/` | + +\* Required when provider is `filesystem` +\*\* Required for cloud storage providers (`aws-s3`, `azureblob`, `google-cloud-storage`) + +## CLI client configuration + +The CLI client requires connection settings to communicate with the ScalarDB Analytics server using a Java properties file (e.g., `client.properties`). + +### Configuration properties + +#### Server connection configuration + +| Property | Required | Default | Description | Example | +| ------------------------------------------------- | -------- | ------- | ------------------------------------------------------- | ----------------------- | +| `scalar.db.analytics.client.server.host` | Yes | - | Hostname or IP address of the ScalarDB Analytics server | `analytics.example.com` | +| `scalar.db.analytics.client.server.catalog.port` | No | `11051` | Port number for the catalog service | `11051` | +| `scalar.db.analytics.client.server.metering.port` | No | `11052` | Port number for the metering service | `11052` | + +#### TLS configuration + +| Property | Required | Default | Description | Example | +| ---------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------------- | ------------------- | +| `scalar.db.analytics.client.server.tls.enabled` | No | `false` | Enable TLS/SSL for server connections | `true` | +| `scalar.db.analytics.client.server.tls.ca_root_cert_path` | Yes\* | - | Path to the CA certificate file for verifying server certificates | `/path/to/cert.pem` | +| `scalar.db.analytics.client.server.tls.override_authority` | No | - | Override the server authority for TLS verification (useful for testing) | `test.example.com` | + +\* Required when `tls.enabled` is `true` + +## Spark integration configuration + +To use ScalarDB Analytics with Apache Spark, configure your Spark application by adding the necessary settings to your Spark configuration file (`spark-defaults.conf`). + +### Configuration properties + +#### Core Spark configuration + +| Property | Required | Description | Default | Example | +| ---------------------- | -------- | ----------------------------------------------------- | ------- | ------------------------------------------------------------------ | +| `spark.jars.packages` | Yes | Maven coordinates for ScalarDB Analytics dependencies | - | `com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2` | +| `spark.extraListeners` | Yes | Register the ScalarDB Analytics metering listener | - | `com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener` | + +For `spark.jars.packages`, replace: + +- `` with your Spark version (e.g., `3.5`) +- `` with your Scala version (e.g., `2.12`) +- `` with the ScalarDB Analytics version (e.g., `3.16.2`) + +#### Catalog configuration + +| Property | Required | Description | Default | Value | +| ---------------------------------- | -------- | ------------------------------------------------------ | ------- | ---------------------------------------------------------------- | +| `spark.sql.catalog.` | Yes | Register the ScalarDB Analytics catalog implementation | - | `com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog` | + +#### Server connection settings + +| Property | Required | Default | Description | Example | +| ------------------------------------------------------- | -------- | ------- | ------------------------------------------------------- | ----------- | +| `spark.sql.catalog..server.host` | Yes | - | Hostname or IP address of the ScalarDB Analytics server | `localhost` | +| `spark.sql.catalog..server.catalog.port` | No | `11051` | Port number for the catalog service | `11051` | +| `spark.sql.catalog..server.metering.port` | No | `11052` | Port number for the metering service | `11052` | + +#### TLS/SSL settings + +| Property | Required | Default | Description | Example | +| ---------------------------------------------------------------- | -------- | ------- | ----------------------------------------------------------------- | ------------------- | +| `spark.sql.catalog..server.tls.enabled` | No | `false` | Enable TLS/SSL for server connections | `true` | +| `spark.sql.catalog..server.tls.ca_root_cert_path` | Yes\* | - | Path to the CA certificate file for verifying server certificates | `/path/to/cert.pem` | +| `spark.sql.catalog..server.tls.override_authority` | No | - | Override the server authority for TLS verification | `test.example.com` | + +\* Required when `tls.enabled` is `true` + +Replace `` with your chosen catalog name (e.g., `analytics`). + +## Configuration examples + +### Basic development configuration + +#### Server configuration (`scalardb-analytics-server.properties`) + +```properties +# Metadata database +scalar.db.analytics.server.db.url=jdbc:postgresql://localhost:5432/scalardb_analytics +scalar.db.analytics.server.db.username=dev_user +scalar.db.analytics.server.db.password=dev_password + +# License +scalar.db.analytics.server.licensing.license_key=YOUR_DEV_LICENSE_KEY +scalar.db.analytics.server.licensing.license_check_cert_path=/path/to/license_cert.pem + +# Metering storage (filesystem for development) +scalar.db.analytics.server.metering.storage.provider=filesystem +scalar.db.analytics.server.metering.storage.path=/tmp/scalardb-analytics-metering +``` + +#### Client configuration (`client.properties`) + +```properties +scalar.db.analytics.client.server.host=localhost +``` + +#### Spark configuration (`spark-defaults.conf`) + +```properties +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2 +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener +spark.sql.catalog.analytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.analytics.server.host localhost +``` + +### Production configuration with TLS + +#### Server configuration (`scalardb-analytics-server.properties`) + +```properties +# Metadata database +scalar.db.analytics.server.db.url=jdbc:postgresql://db.internal:5432/scalardb_analytics_prod +scalar.db.analytics.server.db.username=analytics_prod +scalar.db.analytics.server.db.password=your_secure_password + +# gRPC ports +scalar.db.analytics.server.catalog.port=11051 +scalar.db.analytics.server.metering.port=11052 + +# TLS +scalar.db.analytics.server.tls.enabled=true +scalar.db.analytics.server.tls.cert_chain_path=/path/to/server.crt +scalar.db.analytics.server.tls.private_key_path=/path/to/server.key + +# License +scalar.db.analytics.server.licensing.license_key=YOUR_LICENSE_KEY +scalar.db.analytics.server.licensing.license_check_cert_pem=-----BEGIN CERTIFICATE-----\nMIID...certificate content...\n-----END CERTIFICATE----- + +# Metering storage (S3) +scalar.db.analytics.server.metering.storage.provider=aws-s3 +scalar.db.analytics.server.metering.storage.containerName=analytics-metering +scalar.db.analytics.server.metering.storage.accessKeyId=AKIAIOSFODNN7EXAMPLE +scalar.db.analytics.server.metering.storage.secretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +scalar.db.analytics.server.metering.storage.prefix=prod/ +``` + +#### Client configuration (`client.properties`) + +```properties +scalar.db.analytics.client.server.host=analytics.example.com +scalar.db.analytics.client.server.tls.enabled=true +scalar.db.analytics.client.server.tls.ca_root_cert_path=/path/to/cert.pem +``` + +#### Spark configuration (`spark-defaults.conf`) + +```properties +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2 +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener +spark.sql.catalog.analytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.analytics.server.host analytics.example.com +spark.sql.catalog.analytics.server.tls.enabled true +spark.sql.catalog.analytics.server.tls.ca_root_cert_path /path/to/cert.pem +``` + +## Next steps + +- [Run analytical queries](run-analytical-queries.mdx) - Start running queries with your configuration +- [Deployment guide](deployment.mdx) - Deploy ScalarDB Analytics in production diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/administration.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/administration.mdx new file mode 100644 index 00000000..b25e0072 --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/administration.mdx @@ -0,0 +1,794 @@ +--- +tags: + - Enterprise Option +displayed_sidebar: docsJapanese +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# ScalarDB Analytics を管理する + +import WarningLicenseKeyContact from "/src/components/ja-jp/_warning-license-key-contact.mdx"; +import TranslationBanner from "/src/components/_translation-ja-jp.mdx"; + + + +このガイドでは、ScalarDB Analytics サーバーとそのカタログのセットアップと管理方法を説明します。ScalarDB Analytics サーバーは [ScalarDB Analytics 設計](design.mdx) で説明されている Universal Data Catalog の実装であり、複数のデータベース間での分析クエリのための集中型メタデータ管理を提供します。 + + + +## 概要 + +ScalarDB Analytics は、単一のインターフェースを通じて複数のデータベースへの統一されたアクセスを可能にするユニバーサルデータカタログを提供します。[ScalarDB Analytics 設計](design.mdx#universal-data-catalog) ドキュメントで説明されている Universal Data Catalog アーキテクチャに基づき、システムは以下の2つの主要コンポーネントで構成されています： + +1. **ScalarDB Analytics サーバー**: 以下を管理する gRPC ベースのサービス： + - **カタログメタデータ**: データソース、名前空間、テーブル、カラムを整理 + - **データソース接続**: 外部データベースへの接続情報と認証情報を維持 + - **ライセンス検証**: エンタープライズライセンスを検証 + - **使用量メータリング**: 課金目的でリソース使用量を追跡 + + サーバーは 2 つの gRPC エンドポイントを提供します： + - ポート 11051: メタデータ操作のためのカタログサービス + - ポート 11052: 使用量追跡のためのメータリングサービス + +2. **ScalarDB Analytics CLI**: サーバーと通信してカタログの管理、データソースの登録、管理タスクを実行するコマンドラインツール + +## セットアップ + +カタログを管理する前に、ScalarDB Analytics サーバーと CLI をセットアップして設定する必要があります。 + +### サーバーのセットアップ + +#### 前提条件: メタデータデータベース + +サーバーはカタログメタデータとデータソース接続情報を保存するためのデータベースが必要です。このドキュメント全体で、このデータベースを**メタデータデータベース**と呼びます。ScalarDB Analytics は以下のデータベースをメタデータデータベースとしてサポートしています： + +- PostgreSQL +- MySQL +- SQL Server +- Oracle + +サーバーを起動する前に、データベースと適切な権限を持つユーザーを作成してください。具体的なコマンドはデータベースタイプによって異なります。 + +#### サーバー設定 + +サーバー設定ファイルを作成します（例：`scalardb-analytics-server.properties`）。以下の例では PostgreSQL をメタデータデータベースとして使用しています： + +```properties +# メタデータデータベース設定（必須） +scalar.db.analytics.server.db.url=jdbc:postgresql://localhost:5432/scalardb_analytics +scalar.db.analytics.server.db.username=analytics_user +scalar.db.analytics.server.db.password=your_secure_password + +# gRPC サーバー設定（オプション） +scalar.db.analytics.server.catalog.port=11051 # デフォルト +scalar.db.analytics.server.metering.port=11052 # デフォルト + +# TLS 設定（オプション、本番環境では推奨） +scalar.db.analytics.server.tls.enabled=true +scalar.db.analytics.server.tls.cert_chain_path=/path/to/server.crt +scalar.db.analytics.server.tls.private_key_path=/path/to/server.key + +# ライセンス設定（必須） +scalar.db.analytics.server.licensing.license_key= +scalar.db.analytics.server.licensing.license_check_cert_pem= + +# メータリングストレージ設定（必須） +scalar.db.analytics.server.metering.storage.provider=filesystem +scalar.db.analytics.server.metering.storage.path=/var/scalardb-analytics/metering +``` + +詳細な設定オプションについては、[設定リファレンス](configuration.mdx)を参照してください。 + +#### サーバーの起動 + +設定ファイルを使用して ScalarDB Analytics サーバーを起動します： + +```console +docker run -d \ + --name scalardb-analytics-server \ + -p 11051:11051 \ + -p 11052:11052 \ + -v /path/to/scalardb-analytics-server.properties:/scalardb-analytics-server/server.properties \ + ghcr.io/scalar-labs/scalardb-analytics-server: +``` + +`` を使用したい ScalarDB Analytics のバージョンに置き換えてください。利用可能なバージョンは [Docker レジストリページ](https://github.com/scalar-labs/scalardb-analytics/pkgs/container/scalardb-analytics-server) で確認できます。 + +コンテナはデフォルトで `/scalardb-analytics-server/server.properties` の設定ファイルを使用します。 + +サーバーは起動時に以下を実行します： +1. ライセンスを検証 +2. メタデータデータベースに接続 +3. 設定されたポートで gRPC サービスを開始 +4. クライアント接続の受け入れを開始 + +#### ヘルスチェック（オプション） + +サーバーが正常に動作していることを確認したい場合は、grpc-health-probe（Dockerコンテナに含まれています）を使用できます： + +```console +# カタログサービスのヘルスチェック +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11051 + +# メータリングサービスのヘルスチェック +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11052 + +# TLS有効化サーバーの場合 +docker exec scalardb-analytics-server grpc-health-probe -addr=localhost:11051 -tls -tls-ca-cert=/path/to/ca.crt +``` + +### CLI のセットアップ + +#### CLI のインストール + +`scalardb-analytics-cli` ツールは Docker イメージとして利用可能です： + +```console +# CLI イメージをプル +docker pull ghcr.io/scalar-labs/scalardb-analytics-cli: +``` + +`` を使用したい ScalarDB Analytics のバージョンに置き換えてください。利用可能なバージョンは [Docker レジストリページ](https://github.com/scalar-labs/scalardb-analytics/pkgs/container/scalardb-analytics-cli) で確認できます。 + +CLI コマンドを実行するには、設定ファイルをコンテナにマウントする必要があります： + +```console +# 例：カタログを一覧表示 +docker run --rm \ + -v $(pwd)/client.properties:/config/client.properties:ro \ + ghcr.io/scalar-labs/scalardb-analytics-cli: \ + -c /config/client.properties \ + catalog list +``` + +#### クライアント設定 + +現在のディレクトリに `client.properties` という名前の設定ファイルを作成します： + +```properties +# サーバー接続 +scalar.db.analytics.client.server.host=localhost +scalar.db.analytics.client.server.catalog.port=11051 +scalar.db.analytics.client.server.metering.port=11052 + +# TLS/SSL 設定（サーバーで有効な場合） +scalar.db.analytics.client.server.tls.enabled=true +scalar.db.analytics.client.server.tls.ca_root_cert_path=/path/to/ca.crt +scalar.db.analytics.client.server.tls.override_authority=analytics.example.com +``` + +詳細な設定オプションについては、[設定リファレンス](configuration.mdx)を参照してください。 + +#### エイリアスの設定（オプション） + +便利のため、長い Docker コマンドを毎回入力することを避けるためにエイリアスを作成できます： + +```console +alias scalardb-analytics-cli='docker run --rm -v $(pwd)/client.properties:/config/client.properties:ro ghcr.io/scalar-labs/scalardb-analytics-cli: -c /config/client.properties' +``` + +このエイリアスを使用すると、より簡単にコマンドを実行できます： + +```console +scalardb-analytics-cli catalog list +``` + +## CLI コマンドリファレンス + +ScalarDB Analytics CLI は階層構造のコマンドを使用します： + +``` +scalardb-analytics [options] +``` + +利用可能なリソース： +- **catalog**: データソースを整理するためのトップレベルコンテナ +- **data-source**: カタログ内に登録された外部データベース +- **namespace**: データベース固有の組織単位（自動検出） +- **table**: 名前空間内のデータ構造（自動検出） + +注：以下のすべての例では、前に作成した Docker エイリアスを使用していることを想定しています。Docker コマンドを直接実行する場合は、`scalardb-analytics-cli` を完全な Docker コマンドに置き換えてください。 + +### カタログ操作 + +```console +# 新しいカタログを作成 +scalardb-analytics-cli catalog create --catalog + +# すべてのカタログを一覧表示 +scalardb-analytics-cli catalog list + +# カタログの詳細を表示（名前または ID で） +scalardb-analytics-cli catalog describe --catalog +scalardb-analytics-cli catalog describe --catalog-id + +# カタログを削除（空でない場合は --cascade が必要） +scalardb-analytics-cli catalog delete --catalog +scalardb-analytics-cli catalog delete --catalog --cascade +``` + +### データソース操作 + +```console +# JSON 定義ファイルを使用して新しいデータソースを登録 +scalardb-analytics-cli data-source register --data-source-json + +# カタログ内のすべてのデータソースを一覧表示 +scalardb-analytics-cli data-source list --catalog + +# データソースの詳細を表示（名前または ID で） +scalardb-analytics-cli data-source describe --catalog --data-source +scalardb-analytics-cli data-source describe --data-source-id + +# データソースを削除（空でない場合は --cascade が必要） +scalardb-analytics-cli data-source delete --catalog --data-source +scalardb-analytics-cli data-source delete --catalog --data-source --cascade +``` + +`register` コマンドには JSON 定義ファイルが必要です。JSON ファイル形式については、下記の[データソース設定](#データソース設定)セクションを参照してください。 + +### 名前空間操作 + +```console +# データソース内のすべての名前空間を一覧表示 +scalardb-analytics-cli namespace list --catalog --data-source + +# 名前空間の詳細を表示（名前または ID で） +# ネストされた名前空間の場合、'.' を区切り文字として使用（例：--namespace parent.child） +scalardb-analytics-cli namespace describe --catalog --data-source --namespace +scalardb-analytics-cli namespace describe --namespace-id +``` + +### テーブル操作 + +```console +# 名前空間内のすべてのテーブルを一覧表示 +scalardb-analytics-cli table list --catalog --data-source --namespace + +# すべてのカラムを含むテーブルスキーマを表示（名前または ID で） +# ネストされた名前空間の場合、'.' を区切り文字として使用（例：--namespace parent.child） +scalardb-analytics-cli table describe --catalog --data-source --namespace --table +scalardb-analytics-cli table describe --table-id +``` + +## データソース設定 + +### データソース JSON 形式 + +データソースは以下の構造を持つ JSON 定義ファイルを使用して登録されます： + +```json +{ + "catalog": "", // データソースを登録するカタログ + "name": "", // このデータソースの一意の名前 + "type": "", // データベースタイプ: postgres, mysql, scalardb, sqlserver, oracle, dynamodb + "provider": { // タイプ固有の接続設定 + // 設定はデータベースタイプによって異なります + } +} +``` + +`provider` セクションには、`type` フィールドに基づいたデータベース固有の接続設定が含まれます。 + +### タイプ別の Provider 設定 + +以下のセクションでは、サポートされている各データベースタイプの Provider 設定を示します： + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ------------ | -------- | --------------------------------------- | ------- | +| `configPath` | はい | ScalarDB 設定ファイルへのパス | - | + +**例:** + +```json +{ + "catalog": "production", + "name": "scalardb_source", + "type": "scalardb", + "provider": { + "configPath": "/path/to/scalardb.properties" + } +} +``` + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ---------- | -------- | --------------------------- | ------- | +| `host` | はい | PostgreSQL サーバーのホスト名 | - | +| `port` | はい | ポート番号 | - | +| `username` | はい | データベースユーザー | - | +| `password` | はい | データベースパスワード | - | +| `database` | はい | 接続するデータベース名 | - | + +**例:** + +```json +{ + "catalog": "production", + "name": "postgres_customers", + "type": "postgres", + "provider": { + "host": "postgres.example.com", + "port": 5432, + "username": "analytics_user", + "password": "secure_password", + "database": "customers" + } +} +``` + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ---------- | -------- | ----------------------------------------------------------------------- | ------- | +| `host` | はい | MySQL サーバーのホスト名 | - | +| `port` | はい | ポート番号 | - | +| `username` | はい | データベースユーザー | - | +| `password` | はい | データベースパスワード | - | +| `database` | いいえ | インポートする特定のデータベース。省略した場合、すべてのデータベースがインポートされます | - | + +**例:** + +```json +{ + "catalog": "production", + "name": "mysql_orders", + "type": "mysql", + "provider": { + "host": "mysql.example.com", + "port": 3306, + "username": "analytics_user", + "password": "secure_password", + "database": "orders" // オプション - 省略した場合、すべてのデータベースがインポートされます + } +} +``` + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ------------- | -------- | ----------------- | ------- | +| `host` | はい | Oracle サーバーのホスト名 | - | +| `port` | はい | ポート番号 | - | +| `username` | はい | データベースユーザー | - | +| `password` | はい | データベースパスワード | - | +| `serviceName` | はい | Oracle サービス名 | - | + +**例:** + +```json +{ + "catalog": "production", + "name": "oracle_warehouse", + "type": "oracle", + "provider": { + "host": "oracle.example.com", + "port": 1521, + "username": "analytics_user", + "password": "secure_password", + "serviceName": "ORCL" + } +} +``` + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ---------- | -------- | -------------------------------- | ------- | +| `host` | はい | SQL Server のホスト名 | - | +| `port` | はい | ポート番号 | - | +| `username` | はい | データベースユーザー | - | +| `password` | はい | データベースパスワード | - | +| `database` | いいえ | 接続する特定のデータベース | - | +| `secure` | いいえ | 暗号化を有効化 | - | + +**例:** + +```json +{ + "catalog": "production", + "name": "sqlserver_analytics", + "type": "sqlserver", + "provider": { + "host": "sqlserver.example.com", + "port": 1433, + "username": "sa", + "password": "secure_password", + "database": "analytics", // オプション - 指定した場合、このデータベースのみがインポートされます + "secure": true // オプション - 暗号化を有効化 + } +} +``` + + + + +#### 設定 + +| フィールド | 必須 | 説明 | デフォルト | +| ---------- | -------- | --------------------------------------------------- | ------- | +| `region` | はい* | AWS リージョン（例: us-east-1） | - | +| `endpoint` | はい* | カスタムエンドポイント URL | - | +| `schema` | はい | 完全なスキーマ定義 | - | + +\* `region` または `endpoint` のいずれかを指定する必要があります（両方は指定できません）。 + +DynamoDB はスキーマレスなので、完全なスキーマ定義を提供する必要があります。 + +##### スキーマ構造 + +| フィールド | 必須 | 説明 | デフォルト | +| --------------------------------------- | -------- | ---------------------------------- | ------- | +| `.schema` | はい | 完全なスキーマ定義 | - | +| `.schema.namespaces[]` | はい | 名前空間定義の配列 | - | +| `.schema.namespaces[].names[]` | はい | 名前空間名の配列（文字列） | - | +| `.schema.namespaces[].tables[]` | はい | テーブル定義の配列 | - | +| `.schema.namespaces[].tables[].name` | はい | テーブル名 | - | +| `.schema.namespaces[].tables[].columns[]` | はい | カラム定義の配列 | - | +| `.schema.namespaces[].tables[].columns[].name` | はい | カラム名 | - | +| `.schema.namespaces[].tables[].columns[].type` | はい | データ型 | - | +| `.schema.namespaces[].tables[].columns[].nullable` | いいえ | カラムがnull値を含むことができるかどうか | true | + +**例:** + +```json +{ + "catalog": "production", + "name": "dynamodb_events", + "type": "dynamodb", + "provider": { + "region": "us-east-1", + "schema": { + "namespaces": [ + { + "names": ["production"], + "tables": [ + { + "name": "user_events", + "columns": [ + {"name": "user_id", "type": "TEXT", "nullable": false}, + {"name": "event_time", "type": "TIMESTAMP", "nullable": false}, + {"name": "event_type", "type": "TEXT"}, + {"name": "event_data", "type": "TEXT"} + ] + } + ] + } + ] + } + } +} +``` + + + + +## カタログメタデータリファレンス + +### データソース別のカタログ構造マッピング + +データソースを ScalarDB Analytics に登録する際、データソースのカタログ構造（名前空間、テーブル、列など）が解決され、ユニバーサルデータカタログに登録されます。データソースのカタログ構造を解決するために、データソース側の特定のオブジェクトがユニバーサルデータカタログオブジェクトにマッピングされます。 + +#### カタログレベルのマッピング + +カタログレベルのマッピングは、データソースから名前空間名、テーブル名、および列名をユニバーサルデータカタログへのマッピングです。各データソースでのカタログレベルのマッピングを確認するには、データソースを選択してください。 + + + + ScalarDB のカタログ構造は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： + + - ScalarDB 名前空間は名前空間にマッピングされます。したがって、ScalarDB データソースの名前空間は常に単一レベルで、名前空間名のみで設定されます。 + - ScalarDB テーブルはテーブルにマッピングされます。 + - ScalarDB 列は列にマッピングされます。 + + + + + PostgreSQL のカタログ構造は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： + + - PostgreSQL スキーマは名前空間にマッピングされます。したがって、PostgreSQL データソースの名前空間は常に単一レベルで、スキーマ名のみで設定されます。 + - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： + - `information_schema` + - `pg_catalog` + - PostgreSQL テーブルはテーブルにマッピングされます。 + - PostgreSQL 列は列にマッピングされます。 + + + + MySQL のカタログ構造は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： + + - MySQL データベースは名前空間にマッピングされます。したがって、MySQL データソースの名前空間は常に単一レベルで、データベース名のみで設定されます。 + - ユーザー定義データベースのみが名前空間にマッピングされます。以下のシステムデータベースは無視されます： + - `mysql` + - `sys` + - `information_schema` + - `performance_schema` + - MySQL テーブルはテーブルにマッピングされます。 + - MySQL 列は列にマッピングされます。 + + + + Oracle のカタログ構造は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： + + - Oracle スキーマは名前空間にマッピングされます。したがって、Oracle データソースの名前空間は常に単一レベルで、スキーマ名のみで設定されます。 + - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： + - `ANONYMOUS` + - `APPQOSSYS` + - `AUDSYS` + - `CTXSYS` + - `DBSNMP` + - `DGPDB_INT` + - `DBSFWUSER` + - `DVF` + - `DVSYS` + - `GGSYS` + - `GSMADMIN_INTERNAL` + - `GSMCATUSER` + - `GSMROOTUSER` + - `GSMUSER` + - `LBACSYS` + - `MDSYS` + - `OJVMSYS` + - `ORDDATA` + - `ORDPLUGINS` + - `ORDSYS` + - `OUTLN` + - `REMOTE_SCHEDULER_AGENT` + - `SI_INFORMTN_SCHEMA` + - `SYS` + - `SYS$UMF` + - `SYSBACKUP` + - `SYSDG` + - `SYSKM` + - `SYSRAC` + - `SYSTEM` + - `WMSYS` + - `XDB` + - `DIP` + - `MDDATA` + - `ORACLE_OCM` + - `XS$NULL` + + + + SQL Server のカタログ構造は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： + + - SQL Server データベースとスキーマは共に名前空間にマッピングされます。したがって、SQL Server データソースの名前空間は常に二段階で、データベース名とスキーマ名で構成されます。 + - ユーザー定義データベースのみが名前空間にマッピングされます。以下のシステムデータベースは無視されます： + - `sys` + - `guest` + - `INFORMATION_SCHEMA` + - `db_accessadmin` + - `db_backupoperator` + - `db_datareader` + - `db_datawriter` + - `db_ddladmin` + - `db_denydatareader` + - `db_denydatawriter` + - `db_owner` + - `db_securityadmin` + - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： + - `master` + - `model` + - `msdb` + - `tempdb` + - SQL Server テーブルはテーブルにマッピングされます。 + - SQL Server 列は列にマッピングされます。 + + + + DynamoDB はスキーマレスであるため、DynamoDB データソースを登録する際に以下のような形式のJSONを使用してカタログ構造を明示的に指定する必要があります： + + ```json + { + "namespaces": [ + { + "name": "", + "tables": [ + { + "name": "", + "columns": [ + { + "name": "", + "type": "" + }, + ... + ] + }, + ... + ] + }, + ... + ] + } + ``` + + 指定した JSON では、任意の名前空間名を使用できますが、テーブル名は DynamoDB のテーブル名と一致する必要があり、列名と型は DynamoDB のフィールド名と型と一致する必要があります。 + + + + +### データタイプマッピング + +以下のセクションでは、各データソースのネイティブタイプが ScalarDB Analytics タイプにどのようにマッピングされるかを示します： + + + + +| **ScalarDB データタイプ** | **ScalarDB Analytics データタイプ** | +|:------------------------------|:---------------------------------| +| `BOOLEAN` | `BOOLEAN` | +| `INT` | `INT` | +| `BIGINT` | `BIGINT` | +| `FLOAT` | `FLOAT` | +| `DOUBLE` | `DOUBLE` | +| `TEXT` | `TEXT` | +| `BLOB` | `BLOB` | +| `DATE` | `DATE` | +| `TIME` | `TIME` | +| `TIMESTAMP` | `TIMESTAMP` | +| `TIMESTAMPTZ` | `TIMESTAMPTZ` | + + + + +| **PostgreSQL データタイプ** | **ScalarDB Analytics データタイプ** | +|:------------------------------|:---------------------------------| +| `integer` | `INT` | +| `bigint` | `BIGINT` | +| `real` | `FLOAT` | +| `double precision` | `DOUBLE` | +| `smallserial` | `SMALLINT` | +| `serial` | `INT` | +| `bigserial` | `BIGINT` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `text` | `TEXT` | +| `bpchar` | `TEXT` | +| `boolean` | `BOOLEAN` | +| `bytea` | `BLOB` | +| `date` | `DATE` | +| `time` | `TIME` | +| `time with time zone` | `TIME` | +| `time without time zone` | `TIME` | +| `timestamp` | `TIMESTAMP` | +| `timestamp with time zone` | `TIMESTAMPTZ` | +| `timestamp without time zone` | `TIMESTAMP` | + + + + +| **MySQL データタイプ** | **ScalarDB Analytics データタイプ** | +|:-----------------------|:---------------------------------| +| `bit` | `BOOLEAN` | +| `bit(1)` | `BOOLEAN` | +| `bit(x)` if *x >= 2* | `BLOB` | +| `tinyint` | `SMALLINT` | +| `tinyint(1)` | `BOOLEAN` | +| `boolean` | `BOOLEAN` | +| `smallint` | `SMALLINT` | +| `smallint unsigned` | `INT` | +| `mediumint` | `INT` | +| `mediumint unsigned` | `INT` | +| `int` | `INT` | +| `int unsigned` | `BIGINT` | +| `bigint` | `BIGINT` | +| `float` | `FLOAT` | +| `double` | `DOUBLE` | +| `real` | `DOUBLE` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `text` | `TEXT` | +| `binary` | `BLOB` | +| `varbinary` | `BLOB` | +| `blob` | `BLOB` | +| `date` | `DATE` | +| `time` | `TIME` | +| `datetime` | `TIMESTAMP` | +| `timestamp` | `TIMESTAMPTZ` | + + + + +| **Oracle データタイプ** | **ScalarDB Analytics データタイプ** | +|:-----------------------------------|:---------------------------------| +| `NUMBER` if *scale = 0* | `BIGINT` | +| `NUMBER` if *scale > 0* | `DOUBLE` | +| `FLOAT` if *precision ≤ 53* | `DOUBLE` | +| `BINARY_FLOAT` | `FLOAT` | +| `BINARY_DOUBLE` | `DOUBLE` | +| `CHAR` | `TEXT` | +| `NCHAR` | `TEXT` | +| `VARCHAR2` | `TEXT` | +| `NVARCHAR2` | `TEXT` | +| `CLOB` | `TEXT` | +| `NCLOB` | `TEXT` | +| `BLOB` | `BLOB` | +| `BOOLEAN` | `BOOLEAN` | +| `DATE` | `DATE` | +| `TIMESTAMP` | `TIMESTAMPTZ` | +| `TIMESTAMP WITH TIME ZONE` | `TIMESTAMPTZ` | +| `TIMESTAMP WITH LOCAL TIME ZONE` | `TIMESTAMP` | +| `RAW` | `BLOB` | + + + + +| **SQL Server データタイプ** | **ScalarDB Analytics データタイプ** | +|:---------------------------|:---------------------------------| +| `bit` | `BOOLEAN` | +| `tinyint` | `SMALLINT` | +| `smallint` | `SMALLINT` | +| `int` | `INT` | +| `bigint` | `BIGINT` | +| `real` | `FLOAT` | +| `float` | `DOUBLE` | +| `float(n)` if *n ≤ 24* | `FLOAT` | +| `float(n)` if *n ≥ 25* | `DOUBLE` | +| `binary` | `BLOB` | +| `varbinary` | `BLOB` | +| `char` | `TEXT` | +| `varchar` | `TEXT` | +| `nchar` | `TEXT` | +| `nvarchar` | `TEXT` | +| `ntext` | `TEXT` | +| `text` | `TEXT` | +| `date` | `DATE` | +| `time` | `TIME` | +| `datetime` | `TIMESTAMP` | +| `datetime2` | `TIMESTAMP` | +| `smalldatetime` | `TIMESTAMP` | +| `datetimeoffset` | `TIMESTAMPTZ` | + + + + +| **DynamoDB データタイプ** | **ScalarDB Analytics データタイプ** | +|:-------------------------|:---------------------------------| +| `Number` | `BYTE` | +| `Number` | `SMALLINT` | +| `Number` | `INT` | +| `Number` | `BIGINT` | +| `Number` | `FLOAT` | +| `Number` | `DOUBLE` | +| `Number` | `DECIMAL` | +| `String` | `TEXT` | +| `Binary` | `BLOB` | +| `Boolean` | `BOOLEAN` | + +:::warning + +`Number` タイプのフィールド値が ScalarDB Analytics で指定されたデータタイプとして解析可能であることを確認することが重要です。たとえば、`Number` タイプフィールドに対応するカラムが `INT` タイプとして指定されている場合、その値は整数でなければなりません。値が整数でない場合、クエリ実行時にエラーが発生します。 + +::: + + + + +## 次のステップ + +ScalarDB Analytics サーバーとカタログ管理をセットアップした後： + +1. カタログを使用するよう Spark やその他のクエリエンジンを設定 - [設定リファレンス](configuration.mdx) を参照 +2. 分析クエリの実行を開始 - [分析クエリの実行](run-analytical-queries.mdx) を参照 +3. 本番デプロイメントをセットアップ - [デプロイメントガイド](deployment.mdx) を参照 \ No newline at end of file diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/configuration.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/configuration.mdx new file mode 100644 index 00000000..e1510d7e --- /dev/null +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/configuration.mdx @@ -0,0 +1,241 @@ +--- +tags: + - Enterprise Option +displayed_sidebar: docsJapanese +--- + +# 設定リファレンス + +このページでは、ScalarDB Analytics のすべてのコンポーネントの設定に関する包括的なリファレンスを提供します。 + +## 概要 + +ScalarDB Analytics は、設定が必要な 3 つの主要コンポーネントで構成されています： + +1. **ScalarDB Analytics サーバー** - カタログとメータリングサービスをホストするサーバー +2. **CLI クライアント** - カタログとデータソースを管理するためのコマンドラインインターフェース +3. **Spark 統合** - Apache Spark で ScalarDB Analytics を使用するための設定 + +## ScalarDB Analytics サーバー設定 + +サーバーは、データベース接続、ネットワーク設定、ライセンス、オプション機能を定義する標準的な Java プロパティファイル（例：`scalardb-analytics-server.properties`）を使用して設定されます。 + +### 設定プロパティ + +#### メタデータデータベース設定 + +サーバーは、カタログ情報を保存するためのメタデータデータベースが必要です。 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.server.db.url` | はい | - | メタデータデータベースの JDBC URL | `jdbc:postgresql://localhost:5432/scalardb_analytics` | +| `scalar.db.analytics.server.db.username` | はい | - | 認証用のデータベースユーザー | `analytics_user` | +| `scalar.db.analytics.server.db.password` | はい | - | 認証用のデータベースパスワード | `your_secure_password` | + +#### gRPC サーバー設定 + +カタログおよびメータリングサービスのポートを設定します。 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.server.catalog.port` | いいえ | `11051` | カタログサービスのポート | `11051` | +| `scalar.db.analytics.server.metering.port` | いいえ | `11052` | メータリングサービスのポート | `11052` | + +#### TLS 設定 + +セキュアな通信のために TLS/SSL を有効にします。 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.server.tls.enabled` | いいえ | `false` | gRPC エンドポイントの TLS/SSL を有効にする | `true` | +| `scalar.db.analytics.server.tls.cert_chain_path` | はい* | - | サーバー証明書チェーンファイルへのパス | `/path/to/server.crt` | +| `scalar.db.analytics.server.tls.private_key_path` | はい* | - | サーバー秘密鍵ファイルへのパス | `/path/to/server.key` | + +\* `tls.enabled` が `true` の場合に必須 + +#### ライセンス設定 + +ScalarDB Analytics ライセンスを設定します。 + +| プロパティ | 必須 | 説明 | デフォルト | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.server.licensing.license_key` | はい | ScalarDB Analytics ライセンスキー | - | ライセンスについては Scalar に連絡 | +| `scalar.db.analytics.server.licensing.license_check_cert_pem` | はい* | PEM 文字列としてのライセンス検証証明書 | - | 証明書については Scalar に連絡 | +| `scalar.db.analytics.server.licensing.license_check_cert_path` | はい* | ライセンス検証証明書ファイルへのパス | - | `/path/to/cert.pem` | + +\* `license_check_cert_pem` または `license_check_cert_path` のいずれかを指定する必要があります + +#### メータリングストレージ設定 + +メータリングデータのストレージを設定します。 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.server.metering.storage.provider` | はい | - | メータリングデータのストレージプロバイダー（`filesystem`、`aws-s3`、`azureblob`、`google-cloud-storage`） | `filesystem` | +| `scalar.db.analytics.server.metering.storage.containerName` | いいえ | `metering` | クラウドストレージ用のコンテナ/バケット名 | `my-metering-bucket` | +| `scalar.db.analytics.server.metering.storage.path` | はい* | - | ローカルディレクトリパス（`filesystem` プロバイダーのみ） | `/var/scalardb-analytics/metering` | +| `scalar.db.analytics.server.metering.storage.accessKeyId` | はい** | - | クラウドストレージプロバイダー用のアクセスキー ID | `AKIAIOSFODNN7EXAMPLE` | +| `scalar.db.analytics.server.metering.storage.secretAccessKey` | はい** | - | クラウドストレージプロバイダー用のシークレットアクセスキー | `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` | +| `scalar.db.analytics.server.metering.storage.prefix` | いいえ | - | すべてのストレージパスのオプションのプレフィックス | `production/` | + +\* プロバイダーが `filesystem` の場合に必須 +\** クラウドストレージプロバイダー（`aws-s3`、`azureblob`、`google-cloud-storage`）の場合に必須 + +## CLI クライアント設定 + +CLI クライアントは、ScalarDB Analytics サーバーと通信するための接続設定を Java プロパティファイル（例：`client.properties`）を使用して設定します。 + +### 設定プロパティ + +#### サーバー接続設定 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.client.server.host` | はい | - | ScalarDB Analytics サーバーのホスト名または IP アドレス | `analytics.example.com` | +| `scalar.db.analytics.client.server.catalog.port` | いいえ | `11051` | カタログサービスのポート番号 | `11051` | +| `scalar.db.analytics.client.server.metering.port` | いいえ | `11052` | メータリングサービスのポート番号 | `11052` | + +#### TLS 設定 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `scalar.db.analytics.client.server.tls.enabled` | いいえ | `false` | サーバー接続の TLS/SSL を有効にする | `true` | +| `scalar.db.analytics.client.server.tls.ca_root_cert_path` | はい* | - | サーバー証明書を検証するための CA 証明書ファイルへのパス | `/path/to/cert.pem` | +| `scalar.db.analytics.client.server.tls.override_authority` | いいえ | - | TLS 検証のためのサーバー権限をオーバーライド（テストに便利） | `test.example.com` | + +\* `tls.enabled` が `true` の場合に必須 + +## Spark 統合設定 + +Apache Spark で ScalarDB Analytics を使用するには、Spark 設定ファイル（`spark-defaults.conf`）に必要な設定を追加して Spark アプリケーションを設定します。 + +### 設定プロパティ + +#### コア Spark 設定 + +| プロパティ | 必須 | 説明 | デフォルト | 例 | +| --- | --- | --- | --- | --- | +| `spark.jars.packages` | はい | ScalarDB Analytics 依存関係の Maven 座標 | - | `com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2` | +| `spark.extraListeners` | はい | ScalarDB Analytics メータリングリスナーを登録 | - | `com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener` | + +`spark.jars.packages` では以下を置換してください： +- `` を Spark バージョンに（例：`3.5`） +- `` を Scala バージョンに（例：`2.12`） +- `` を ScalarDB Analytics バージョンに（例：`3.16.2`） + +#### カタログ設定 + +| プロパティ | 必須 | 説明 | デフォルト | 値 | +| --- | --- | --- | --- | --- | +| `spark.sql.catalog.` | はい | ScalarDB Analytics カタログ実装を登録 | - | `com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog` | + +#### サーバー接続設定 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `spark.sql.catalog..server.host` | はい | - | ScalarDB Analytics サーバーのホスト名または IP アドレス | `localhost` | +| `spark.sql.catalog..server.catalog.port` | いいえ | `11051` | カタログサービスのポート番号 | `11051` | +| `spark.sql.catalog..server.metering.port` | いいえ | `11052` | メータリングサービスのポート番号 | `11052` | + +#### TLS/SSL 設定 + +| プロパティ | 必須 | デフォルト | 説明 | 例 | +| --- | --- | --- | --- | --- | +| `spark.sql.catalog..server.tls.enabled` | いいえ | `false` | サーバー接続の TLS/SSL を有効にする | `true` | +| `spark.sql.catalog..server.tls.ca_root_cert_path` | はい* | - | サーバー証明書を検証するための CA 証明書ファイルへのパス | `/path/to/cert.pem` | +| `spark.sql.catalog..server.tls.override_authority` | いいえ | - | TLS 検証のためのサーバー権限をオーバーライド | `test.example.com` | + +\* `tls.enabled` が `true` の場合に必須 + +`` を選択したカタログ名（例：`analytics`）に置き換えてください。 + +## 設定例 + +### 基本的な開発設定 + +#### サーバー設定（`scalardb-analytics-server.properties`） + +```properties +# メタデータデータベース +scalar.db.analytics.server.db.url=jdbc:postgresql://localhost:5432/scalardb_analytics +scalar.db.analytics.server.db.username=dev_user +scalar.db.analytics.server.db.password=dev_password + +# ライセンス +scalar.db.analytics.server.licensing.license_key=YOUR_DEV_LICENSE_KEY +scalar.db.analytics.server.licensing.license_check_cert_path=/path/to/license_cert.pem + +# メータリングストレージ（開発用に filesystem） +scalar.db.analytics.server.metering.storage.provider=filesystem +scalar.db.analytics.server.metering.storage.path=/tmp/scalardb-analytics-metering +``` + +#### クライアント設定（`client.properties`） + +```properties +scalar.db.analytics.client.server.host=localhost +``` + +#### Spark 設定（`spark-defaults.conf`） + +```properties +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2 +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener +spark.sql.catalog.analytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.analytics.server.host localhost +``` + +### TLS を使用した本番設定 + +#### サーバー設定（`scalardb-analytics-server.properties`） + +```properties +# メタデータデータベース +scalar.db.analytics.server.db.url=jdbc:postgresql://db.internal:5432/scalardb_analytics_prod +scalar.db.analytics.server.db.username=analytics_prod +scalar.db.analytics.server.db.password=your_secure_password + +# gRPC ポート +scalar.db.analytics.server.catalog.port=11051 +scalar.db.analytics.server.metering.port=11052 + +# TLS +scalar.db.analytics.server.tls.enabled=true +scalar.db.analytics.server.tls.cert_chain_path=/path/to/server.crt +scalar.db.analytics.server.tls.private_key_path=/path/to/server.key + +# ライセンス +scalar.db.analytics.server.licensing.license_key=YOUR_LICENSE_KEY +scalar.db.analytics.server.licensing.license_check_cert_pem=-----BEGIN CERTIFICATE-----\nMIID...certificate content...\n-----END CERTIFICATE----- + +# メータリングストレージ（S3） +scalar.db.analytics.server.metering.storage.provider=aws-s3 +scalar.db.analytics.server.metering.storage.containerName=analytics-metering +scalar.db.analytics.server.metering.storage.accessKeyId=AKIAIOSFODNN7EXAMPLE +scalar.db.analytics.server.metering.storage.secretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +scalar.db.analytics.server.metering.storage.prefix=prod/ +``` + +#### クライアント設定（`client.properties`） + +```properties +scalar.db.analytics.client.server.host=analytics.example.com +scalar.db.analytics.client.server.tls.enabled=true +scalar.db.analytics.client.server.tls.ca_root_cert_path=/path/to/cert.pem +``` + +#### Spark 設定（`spark-defaults.conf`） + +```properties +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-3.5_2.12:3.16.2 +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener +spark.sql.catalog.analytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.analytics.server.host analytics.example.com +spark.sql.catalog.analytics.server.tls.enabled true +spark.sql.catalog.analytics.server.tls.ca_root_cert_path /path/to/cert.pem +``` + +## 次のステップ + +- [分析クエリの実行](run-analytical-queries.mdx) - 設定でクエリの実行を開始 +- [デプロイメントガイド](deployment.mdx) - 本番環境での ScalarDB Analytics のデプロイ \ No newline at end of file From cf5c9f23c2f01adcc4d1011cb5bf284d27e2ff37 Mon Sep 17 00:00:00 2001 From: Josh Wong <23216828+josh-wong@users.noreply.github.com> Date: Wed, 6 Aug 2025 18:37:13 +0900 Subject: [PATCH 2/4] Add updated doc (tentative publication) --- docs/scalardb-analytics/design.mdx | 290 +----------------- .../run-analytical-queries.mdx | 257 +++------------- .../current/scalardb-analytics/design.mdx | 290 +----------------- .../run-analytical-queries.mdx | 248 +++------------ 4 files changed, 104 insertions(+), 981 deletions(-) diff --git a/docs/scalardb-analytics/design.mdx b/docs/scalardb-analytics/design.mdx index e1f99d07..3324887c 100644 --- a/docs/scalardb-analytics/design.mdx +++ b/docs/scalardb-analytics/design.mdx @@ -86,294 +86,16 @@ ScalarDB Analytics supports a wide range of data types across different data sou - `DURATION` - `INTERVAL` -### Catalog information mappings by data source +These data types are used across all data sources and provide a unified type system for querying heterogeneous databases. -When registering a data source to ScalarDB Analytics, the catalog information of the data source, that is, namespaces, tables, and columns, are resolved and registered to the universal data catalog. To resolve the catalog information of the data source, a particular object on the data sources side are mapped to the universal data catalog object. This mapping is consists of two parts: catalog-level mappings and data-type mappings. In the following sections, we describe how ScalarDB Analytics maps the catalog level and data type from each data source into the universal data catalog. +### Data source integration -#### Catalog-level mappings +When registering a data source to ScalarDB Analytics, two types of mappings occur: -The catalog-level mappings are the mappings of the namespace names, table names, and column names from the data sources to the universal data catalog. To see the catalog-level mappings in each data source, select a data source. +1. **Catalog structure mapping**: The data source's catalog information (namespaces, tables, and columns) is resolved and mapped to the universal data catalog structure +2. **Data type mapping**: Native data types from each data source are mapped to the universal data types listed above - - - The catalog information of ScalarDB is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: - - - The ScalarDB namespace is mapped to the namespace. Therefore, the namespace of the ScalarDB data source is always single level, consisting of only the namespace name. - - The ScalarDB table is mapped to the table. - - The ScalarDB column is mapped to the column. - - - - - The catalog information of PostgreSQL is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: - - - The PostgreSQL schema is mapped to the namespace. Therefore, the namespace of the PostgreSQL data source is always single level, consisting of only the schema name. - - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: - - `information_schema` - - `pg_catalog` - - The PostgreSQL table is mapped to the table. - - The PostgreSQL column is mapped to the column. - - - - The catalog information of MySQL is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: - - - The MySQL database is mapped to the namespace. Therefore, the namespace of the MySQL data source is always single level, consisting of only the database name. - - Only user-defined databases are mapped to namespaces. The following system databases are ignored: - - `mysql` - - `sys` - - `information_schema` - - `performance_schema` - - The MySQL table is mapped to the table. - - The MySQL column is mapped to the column. - - - - The catalog information of Oracle is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: - - - The Oracle schema is mapped to the namespace. Therefore, the namespace of the Oracle data source is always single level, consisting of only schema name. - - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: - - `ANONYMOUS` - - `APPQOSSYS` - - `AUDSYS` - - `CTXSYS` - - `DBSNMP` - - `DGPDB_INT` - - `DBSFWUSER` - - `DVF` - - `DVSYS` - - `GGSYS` - - `GSMADMIN_INTERNAL` - - `GSMCATUSER` - - `GSMROOTUSER` - - `GSMUSER` - - `LBACSYS` - - `MDSYS` - - `OJVMSYS` - - `ORDDATA` - - `ORDPLUGINS` - - `ORDSYS` - - `OUTLN` - - `REMOTE_SCHEDULER_AGENT` - - `SI_INFORMTN_SCHEMA` - - `SYS` - - `SYS$UMF` - - `SYSBACKUP` - - `SYSDG` - - `SYSKM` - - `SYSRAC` - - `SYSTEM` - - `WMSYS` - - `XDB` - - `DIP` - - `MDDATA` - - `ORACLE_OCM` - - `XS$NULL` - - - - The catalog information of SQL Server is automatically resolved by ScalarDB Analytics. The catalog-level objects are mapped as follows: - - - The SQL Server database and schema are mapped to the namespace together. Therefore, the namespace of the SQL Server data source is always two-level, consisting of the database name and the schema name. - - Only user-defined databases are mapped to namespaces. The following system databases are ignored: - - `sys` - - `guest` - - `INFORMATION_SCHEMA` - - `db_accessadmin` - - `db_backupoperator` - - `db_datareader` - - `db_datawriter` - - `db_ddladmin` - - `db_denydatareader` - - `db_denydatawriter` - - `db_owner` - - `db_securityadmin` - - Only user-defined schemas are mapped to namespaces. The following system schemas are ignored: - - `master` - - `model` - - `msdb` - - `tempdb` - - The SQL Server table is mapped to the table. - - The SQL Server column is mapped to the column. - - - - Since DynamoDB is schema-less, you need to specify the catalog information explicitly when registering a DynamoDB data source by using the following format JSON: - - ```json - { - "namespaces": [ - { - "name": "", - "tables": [ - { - "name": "", - "columns": [ - { - "name": "", - "type": "" - }, - ... - ] - }, - ... - ] - }, - ... - ] - } - ``` - - In the specified JSON, you can use any arbitrary namespace names, but the table names must match the table names in DynamoDB and column name and type must match field names and types in DynamoDB. - - - - -#### Data-type mappings - -The native data types of the underlying data sources are mapped to the data types in ScalarDB Analytics. To see the data-type mappings in each data source, select a data source. - - - - | **ScalarDB Data Type** | **ScalarDB Analytics Data Type** | - |:------------------------------|:---------------------------------| - | `BOOLEAN` | `BOOLEAN` | - | `INT` | `INT` | - | `BIGINT` | `BIGINT` | - | `FLOAT` | `FLOAT` | - | `DOUBLE` | `DOUBLE` | - | `TEXT` | `TEXT` | - | `BLOB` | `BLOB` | - | `DATE` | `DATE` | - | `TIME` | `TIME` | - | `TIMESTAMP` | `TIMESTAMP` | - | `TIMESTAMPTZ` | `TIMESTAMPTZ` | - - - | **PostgreSQL Data Type** | **ScalarDB Analytics Data Type** | - |:------------------------------|:---------------------------------| - | `integer` | `INT` | - | `bigint` | `BIGINT` | - | `real` | `FLOAT` | - | `double precision` | `DOUBLE` | - | `smallserial` | `SMALLINT` | - | `serial` | `INT` | - | `bigserial` | `BIGINT` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `text` | `TEXT` | - | `bpchar` | `TEXT` | - | `boolean` | `BOOLEAN` | - | `bytea` | `BLOB` | - | `date` | `DATE` | - | `time` | `TIME` | - | `time with time zone` | `TIME` | - | `time without time zone` | `TIME` | - | `timestamp` | `TIMESTAMP` | - | `timestamp with time zone` | `TIMESTAMPTZ` | - | `timestamp without time zone` | `TIMESTAMP` | - - - | **MySQL Data Type** | **ScalarDB Analytics Data Type** | - |:-----------------------|:---------------------------------| - | `bit` | `BOOLEAN` | - | `bit(1)` | `BOOLEAN` | - | `bit(x)` if *x >= 2* | `BLOB` | - | `tinyint` | `SMALLINT` | - | `tinyint(1)` | `BOOLEAN` | - | `boolean` | `BOOLEAN` | - | `smallint` | `SMALLINT` | - | `smallint unsigned` | `INT` | - | `mediumint` | `INT` | - | `mediumint unsigned` | `INT` | - | `int` | `INT` | - | `int unsigned` | `BIGINT` | - | `bigint` | `BIGINT` | - | `float` | `FLOAT` | - | `double` | `DOUBLE` | - | `real` | `DOUBLE` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `text` | `TEXT` | - | `binary` | `BLOB` | - | `varbinary` | `BLOB` | - | `blob` | `BLOB` | - | `date` | `DATE` | - | `time` | `TIME` | - | `datetime` | `TIMESTAMP` | - | `timestamp` | `TIMESTAMPTZ` | - - - | **Oracle Data Type** | **ScalarDB Analytics Data Type** | - |:-----------------------------------|:---------------------------------| - | `NUMBER` if *scale = 0* | `BIGINT` | - | `NUMBER` if *scale > 0* | `DOUBLE` | - | `FLOAT` if *precision ≤ 53* | `DOUBLE` | - | `BINARY_FLOAT` | `FLOAT` | - | `BINARY_DOUBLE` | `DOUBLE` | - | `CHAR` | `TEXT` | - | `NCHAR` | `TEXT` | - | `VARCHAR2` | `TEXT` | - | `NVARCHAR2` | `TEXT` | - | `CLOB` | `TEXT` | - | `NCLOB` | `TEXT` | - | `BLOB` | `BLOB` | - | `BOOLEAN` | `BOOLEAN` | - | `DATE` | `DATE` | - | `TIMESTAMP` | `TIMESTAMPTZ` | - | `TIMESTAMP WITH TIME ZONE` | `TIMESTAMPTZ` | - | `TIMESTAMP WITH LOCAL TIME ZONE` | `TIMESTAMP` | - | `RAW` | `BLOB` | - - - | **SQL Server Data Type** | **ScalarDB Analytics Data Type** | - |:---------------------------|:---------------------------------| - | `bit` | `BOOLEAN` | - | `tinyint` | `SMALLINT` | - | `smallint` | `SMALLINT` | - | `int` | `INT` | - | `bigint` | `BIGINT` | - | `real` | `FLOAT` | - | `float` | `DOUBLE` | - | `float(n)` if *n ≤ 24* | `FLOAT` | - | `float(n)` if *n ≥ 25* | `DOUBLE` | - | `binary` | `BLOB` | - | `varbinary` | `BLOB` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `nchar` | `TEXT` | - | `nvarchar` | `TEXT` | - | `ntext` | `TEXT` | - | `text` | `TEXT` | - | `date` | `DATE` | - | `time` | `TIME` | - | `datetime` | `TIMESTAMP` | - | `datetime2` | `TIMESTAMP` | - | `smalldatetime` | `TIMESTAMP` | - | `datetimeoffset` | `TIMESTAMPTZ` | - - - | **DynamoDB Data Type** | **ScalarDB Analytics Data Type** | - |:-------------------------|:---------------------------------| - | `Number` | `BYTE` | - | `Number` | `SMALLINT` | - | `Number` | `INT` | - | `Number` | `BIGINT` | - | `Number` | `FLOAT` | - | `Number` | `DOUBLE` | - | `Number` | `DECIMAL` | - | `String` | `TEXT` | - | `Binary` | `BLOB` | - | `Boolean` | `BOOLEAN` | - -:::warning - -It is important to ensure that the field values of `Number` types are parsable as a specified data type for ScalarDB Analytics. For example, if a column that corresponds to a `Number`-type field is specified as an `INT` type, its value must be an integer. If the value is not an integer, an error will occur when running a query. - -::: - - - +These mappings ensure compatibility and consistency across different database systems. For detailed information about how specific databases are mapped, see [Catalog metadata reference](administration.mdx#catalog-metadata-reference) in the administration guide. ## Query engine diff --git a/docs/scalardb-analytics/run-analytical-queries.mdx b/docs/scalardb-analytics/run-analytical-queries.mdx index 4f4b26aa..98d990cd 100644 --- a/docs/scalardb-analytics/run-analytical-queries.mdx +++ b/docs/scalardb-analytics/run-analytical-queries.mdx @@ -4,8 +4,8 @@ tags: displayed_sidebar: docsEnglish --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; # Run Analytical Queries Through ScalarDB Analytics @@ -19,204 +19,74 @@ This section describes the prerequisites, setting up ScalarDB Analytics in the S ### Prerequisites -ScalarDB Analytics works with Apache Spark 3.4 or later. If you don't have Spark installed yet, please download the Spark distribution from [Apache's website](https://spark.apache.org/downloads.html). +- **ScalarDB Analytics catalog server**: A running instance that manages catalog metadata and connects to your data sources. The server must be set up with at least one data source registered. For setup and data source registration instructions, see [Set up and administer the ScalarDB Analytics catalog server](./administration.mdx). +- **Apache Spark**: A compatible version of Apache Spark. For supported versions, see [Version compatibility](#version-compatibility). If you don't have Spark installed yet, please download the Spark distribution from [Apache's website](https://spark.apache.org/downloads.html). :::note -Apache Spark are built with either Scala 2.12 or Scala 2.13. ScalarDB Analytics supports both versions. You need to be sure which version you are using so that you can select the correct version of ScalarDB Analytics later. You can refer to [Version Compatibility](#version-compatibility) for more details. +Apache Spark are built with either Scala 2.12 or Scala 2.13. ScalarDB Analytics supports both versions. You need to be sure which version you are using so that you can select the correct version of ScalarDB Analytics later. You can refer to [Version compatibility](#version-compatibility) for more details. ::: ### Set up ScalarDB Analytics in the Spark configuration -The following sections describe all available configuration options for ScalarDB Analytics. These configurations control: +ScalarDB Analytics requires specific Spark configurations to integrate with the catalog server. -- How ScalarDB Analytics integrates with Spark -- How data sources are connected and accessed -- How license information is provided +#### Required Spark configurations -For example configurations in a practical scenario, see [the sample application configuration](../scalardb-samples/scalardb-analytics-spark-sample/README.mdx#scalardb-analytics-configuration). +To use ScalarDB Analytics with Spark, you need to configure: -#### Spark plugin configurations +1. **ScalarDB Analytics package**: Add the JAR dependency that matches your Spark and Scala versions +2. **Metering listener**: Register the listener to track resource usage for billing +3. **Catalog registration**: Register a Spark catalog that connects to your ScalarDB Analytics server -| Configuration Key | Required | Description | -|:-----------------|:---------|:------------| -| `spark.jars.packages` | No | A comma-separated list of Maven coordinates for the required dependencies. User need to include the ScalarDB Analytics package you are using, otherwise, specify it as the command line argument when running the Spark application. For details about the Maven coordinates of ScalarDB Analytics, refer to [Add ScalarDB Analytics dependency](#add-the-scalardb-analytics-dependency). | -| `spark.sql.extensions` | Yes | Must be set to `com.scalar.db.analytics.spark.extension.ScalarDbAnalyticsExtensions`. | -| `spark.sql.catalog.` | Yes | Must be set to `com.scalar.db.analytics.spark.ScalarDbAnalyticsCatalog`. | +When configuring Spark, you must specify a catalog name that matches the catalog created on your ScalarDB Analytics server. This ensures Spark can correctly access the data sources managed by that catalog. -You can specify any name for ``. Be sure to use the same catalog name throughout your configuration. - -#### License configurations - -| Configuration Key | Required | Description | -| :--------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------- | -| `spark.sql.catalog..license.key` | Yes | JSON string of the license key for ScalarDB Analytics | -| `spark.sql.catalog..license.cert_pem` | Yes | A string of PEM-encoded certificate of ScalarDB Analytics license. Either `cert_pem` or `cert_path` must be set. | -| `spark.sql.catalog..license.cert_path` | Yes | A path to the PEM-encoded certificate of ScalarDB Analytics license. Either `cert_pem` or `cert_path` must be set. | - -#### Data source configurations - -ScalarDB Analytics supports multiple types of data sources. Each type requires specific configuration parameters: - - - - -:::note - -ScalarDB Analytics supports ScalarDB as a data source. This table describes how to configure ScalarDB as a data source. - -::: - -| Configuration Key | Required | Description | -| :---------------------------------------------------------------------------- | :------- | :---------------------------------------------- | -| `spark.sql.catalog..data_source..type` | Yes | Always set to `scalardb` | -| `spark.sql.catalog..data_source..config_path` | Yes | The path to the configuration file for ScalarDB | - -:::tip - -You can use an arbitrary name for ``. - -::: - - - - -| Configuration Key | Required | Description | -| :------------------------------------------------------------------------- | :------- | :------------------------------------- | -| `spark.sql.catalog..data_source..type` | Yes | Always set to `mysql` | -| `spark.sql.catalog..data_source..host` | Yes | The host name of the MySQL server | -| `spark.sql.catalog..data_source..port` | Yes | The port number of the MySQL server | -| `spark.sql.catalog..data_source..username` | Yes | The username of the MySQL server | -| `spark.sql.catalog..data_source..password` | Yes | The password of the MySQL server | -| `spark.sql.catalog..data_source..database` | No | The name of the database to connect to | - -:::tip - -You can use an arbitrary name for ``. - -::: - - - - -| Configuration Key | Required | Description | -| :------------------------------------------------------------------------- | :------- | :--------------------------------------- | -| `spark.sql.catalog..data_source..type` | Yes | Always set to `postgresql` or `postgres` | -| `spark.sql.catalog..data_source..host` | Yes | The host name of the PostgreSQL server | -| `spark.sql.catalog..data_source..port` | Yes | The port number of the PostgreSQL server | -| `spark.sql.catalog..data_source..username` | Yes | The username of the PostgreSQL server | -| `spark.sql.catalog..data_source..password` | Yes | The password of the PostgreSQL server | -| `spark.sql.catalog..data_source..database` | Yes | The name of the database to connect to | - -:::tip +#### Example configuration -You can use an arbitrary name for ``. +Here's a complete example configuration: -::: +```conf +# 1. ScalarDB Analytics package +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-_: - - +# 2. Metering listener +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener -| Configuration Key | Required | Description | -| :----------------------------------------------------------------------------- | :------- | :------------------------------------ | -| `spark.sql.catalog..data_source..type` | Yes | Always set to `oracle` | -| `spark.sql.catalog..data_source..host` | Yes | The host name of the Oracle server | -| `spark.sql.catalog..data_source..port` | Yes | The port number of the Oracle server | -| `spark.sql.catalog..data_source..username` | Yes | The username of the Oracle server | -| `spark.sql.catalog..data_source..password` | Yes | The password of the Oracle server | -| `spark.sql.catalog..data_source..service_name` | Yes | The service name of the Oracle server | +# 3. Catalog registration +spark.sql.catalog.myanalytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.myanalytics.server.host analytics-server.example.com +spark.sql.catalog.myanalytics.server.catalog.port 11051 +spark.sql.catalog.myanalytics.server.metering.port 11052 +``` -:::tip +Replace the placeholders: -You can use an arbitrary name for ``. +- ``: Your Spark version (e.g., `3.5` or `3.4`) +- ``: Your Scala version (e.g., `2.13` or `2.12`) +- ``: The ScalarDB Analytics version (e.g., `3.16.0`) -::: +In this example: - - - -| Configuration Key | Required | Description | -| :------------------------------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------- | -| `spark.sql.catalog..data_source..type` | Yes | Always set to `sqlserver` or `mssql` | -| `spark.sql.catalog..data_source..host` | Yes | The host name of the SQL Server server | -| `spark.sql.catalog..data_source..port` | Yes | The port number of the SQL Server server | -| `spark.sql.catalog..data_source..username` | Yes | The username of the SQL Server server | -| `spark.sql.catalog..data_source..password` | Yes | The password of the SQL Server server | -| `spark.sql.catalog..data_source..database` | No | The name of the database to connect to | -| `spark.sql.catalog..data_source..secure` | No | Whether to use a secure connection to the SQL Server server. Set to `true` to use a secure connection. | +- The catalog name `myanalytics` must match a catalog that exists on your ScalarDB Analytics server +- The ScalarDB Analytics server is running at `analytics-server.example.com` +- Tables will be accessed using the format: `myanalytics...` -:::tip +:::important -You can use an arbitrary name for ``. +The catalog name in your Spark configuration must match the name of a catalog created on the ScalarDB Analytics server using the CLI. For example, if you created a catalog named `production` on the server, you must use `production` as the catalog name in your Spark configuration properties (e.g., `spark.sql.catalog.production`, `spark.sql.catalog.production.server.host`, etc.). ::: - - - -| Configuration Key | Required | Description | -|:---------------------------------------------------------------------------|:------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `spark.sql.catalog..data_source..type` | Yes | Always set to `dynamodb` | -| `spark.sql.catalog..data_source..region` | Either `region` or `endpoint` must be set | The AWS region of the DynamoDB instance | -| `spark.sql.catalog..data_source..endpoint` | Either `region` or `endpoint` must be set | The AWS endpoint of the DynamoDB instance | -| `spark.sql.catalog..data_source..schema` | Yes | A JSON object representing the schema of the catalog. For details on the format, see [Catalog-level mappings](./design.mdx#catalog-level-mappings). | - - -:::tip +:::note -You can use an arbitrary name for ``. +Data source configurations are managed by the catalog server. For information on configuring data sources in the catalog server, see [Set up and administer the ScalarDB Analytics catalog server](./administration.mdx#configure-data-sources). ::: - - - -#### Example configuration - -Below is an example configuration for ScalarDB Analytics that demonstrates how to set up a catalog named `scalardb` with multiple data sources: - -```conf -# Spark plugin configurations -spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-_: -spark.sql.extensions com.scalar.db.analytics.spark.extension.ScalarDbAnalyticsExtensions -spark.sql.catalog.scalardb com.scalar.db.analytics.spark.ScalarDbAnalyticsCatalog - -# License configurations -spark.sql.catalog.scalardb.license.key -spark.sql.catalog.scalardb.license.cert_pem - -# Data source configurations -spark.sql.catalog.scalardb.data_source.scalardb.type scalardb -spark.sql.catalog.scalardb.data_source.scalardb.config_path /path/to/scalardb.properties - -spark.sql.catalog.scalardb.data_source.mysql_source.type mysql -spark.sql.catalog.scalardb.data_source.mysql_source.host localhost -spark.sql.catalog.scalardb.data_source.mysql_source.port 3306 -spark.sql.catalog.scalardb.data_source.mysql_source.username root -spark.sql.catalog.scalardb.data_source.mysql_source.password password -spark.sql.catalog.scalardb.data_source.mysql_source.database mydb -``` - -The following describes what you should change the content in the angle brackets to: - -- ``: The license key for ScalarDB Analytics -- ``: The PEM-encoded certificate of ScalarDB Analytics license -- ``: The major and minor version of Spark you are using (such as 3.4) -- ``: The major and minor version of Scala that matches your Spark installation (such as 2.12 or 2.13) -- ``: The version of ScalarDB Analytics - -### Add the ScalarDB Analytics dependency - -ScalarDB Analytics is hosted in the Maven Central Repository. The name of the package is `scalardb-analytics-spark-all-_:`, where: - -- ``: The major and minor version of Spark you are using (such as 3.4) -- ``: The major and minor version of Scala that matches your Spark installation (such as 2.12 or 2.13) -- ``: The version of ScalarDB Analytics - -For details about version compatibility, refer to [Version Compatibility](#version-compatibility). +### Build configuration for Spark applications -You can add this dependency to your project by configuring the build settings of your project. For example, if you are using Gradle, you can add the following to your `build.gradle` file: +When developing Spark applications that use ScalarDB Analytics, you can add the dependency to your build configuration. For example, with Gradle: ```groovy dependencies { @@ -226,7 +96,7 @@ dependencies { :::note -If you want bundle your application in a single fat JAR file by using plugins like Gradle Shadow plugin or Maven Shade plugin, you need to exclude ScalarDB Analytics from the fat JAR file by choosing the appropriate configuration, such as `provided` or `shadow`, depending on the plugin you are using. +If you bundle your application in a fat JAR using plugins like Gradle Shadow or Maven Shade, exclude ScalarDB Analytics from the fat JAR by using configurations such as `provided` or `shadow`. ::: @@ -246,10 +116,10 @@ Depending on your environment, you may not be able to use all the methods mentio ::: -With all these methods, you can refer to tables in ScalarDB Analytics using the same table identifier format. For details about how ScalarDB Analytics maps catalog information from data sources, refer to [Catalog information mappings by data source](./design.mdx#catalog-information-mappings-by-data-source). +With all these methods, you can refer to tables in ScalarDB Analytics using the same table identifier format. For details about how ScalarDB Analytics maps catalog information from data sources, refer to [Catalog metadata reference](./administration.mdx#catalog-metadata-reference). - + You can use a commonly used `SparkSession` class for ScalarDB Analytics. Additionally, you can use any type of cluster deployment that Spark supports, such as YARN, Kubernetes, standalone, or local mode. @@ -263,7 +133,7 @@ dependencies { } ``` -Below is an example of a Spark Driver application: +Below is an example of a Spark driver application: ```java import org.apache.spark.sql.SparkSession; @@ -300,7 +170,7 @@ You can also use other CLI tools that Spark provides, such as `spark-sql` and `s -You can use [Spark Connect](https://spark.apache.org/spark-connect/) to interact with ScalarDB Analytics. By using Spark Connect, you can access a remote Spark cluster and read data in the same way as a Spark Driver application. The following briefly describes how to use Spark Connect. +You can use [Spark Connect](https://spark.apache.org/spark-connect/) to interact with ScalarDB Analytics. By using Spark Connect, you can access a remote Spark cluster and read data in the same way as a Spark driver application. The following briefly describes how to use Spark Connect. First, you need to start a Spark Connect server in the remote Spark cluster by running the following command: @@ -367,13 +237,9 @@ ScalarDB Analytics manages its own catalog, containing data sources, namespaces, For details about how information in the raw data sources is mapped to the ScalarDB Analytics catalog, refer to [Catalog information mappings by data source](./design.mdx#catalog-information-mappings-by-data-source). -### Catalog level mapping - -Each catalog level object in the ScalarDB Analytics catalog is mapped to a Spark catalog. The following table shows how the catalog levels are mapped: +### Catalog structure mapping -#### Data source tables - -Tables from data sources in the ScalarDB Analytics catalog are mapped to Spark tables. The following format is used to represent the identity of the Spark tables that correspond to ScalarDB Analytics tables: +ScalarDB Analytics maps catalog structure from data sources to Spark catalogs. Tables from data sources in the ScalarDB Analytics catalog are mapped to Spark tables using the following format: ```console ... @@ -388,39 +254,12 @@ The following describes what you should change the content in the angle brackets For example, if you have a ScalarDB catalog named `my_catalog` that contains a data source named `my_data_source` and a schema named `my_schema`, you can refer to the table named `my_table` in that schema as `my_catalog.my_data_source.my_schema.my_table`. -#### Views - -Views in ScalarDB Analytics are provided as tables in the Spark catalog, not views. The following format is used to represent the identity of the Spark tables that correspond to ScalarDB Analytics views: - -```console -.view.. -``` - -The following describes what you should change the content in the angle brackets to: - -- ``: The name of the catalog. -- ``: The names of the view namespaces. If the view namespace names are multi-level, they are concatenated with a dot (`.`) as the separator. -- ``: The name of the view. - -For example, if you have a ScalarDB catalog named `my_catalog` and a view namespace named `my_view_namespace`, you can refer to the view named `my_view` in that namespace as `my_catalog.view.my_view_namespace.my_view`. - -:::note - -`view` is prefixed to avoid conflicts with the data source table identifier. - -::: - -##### WAL-interpreted views - -As explained in [ScalarDB Analytics Design](./design.mdx), ScalarDB Analytics provides a functionality called WAL-interpreted views, which is a special type of views. These views are automatically created for tables of ScalarDB data sources to provide a user-friendly view of the data by interpreting WAL-metadata in the tables. - -Since the data source name and the namespace names of the original ScalarDB tables are used as the view namespace names for WAL-interpreted views, if you have a ScalarDB table named `my_table` in a namespace named `my_namespace` of a data source named `my_data_source`, you can refer to the WAL-interpreted view of the table as `my_catalog.view.my_data_source.my_namespace.my_table`. ### Data-type mapping ScalarDB Analytics maps data types in its catalog to Spark data types. The following table shows how the data types are mapped: -| ScalarDB Data Type | Spark Data Type | +| ScalarDB data type | Spark data type | | :----------------- | :----------------- | | `BYTE` | `Byte` | | `SMALLINT` | `Short` | @@ -448,6 +287,6 @@ Regarding the Java version, ScalarDB Analytics supports Java 8 or later. The following is a list of Spark and Scalar versions supported by each version of ScalarDB Analytics. | ScalarDB Analytics Version | ScalarDB Version | Spark Versions Supported | Scala Versions Supported | Minimum Java Version | -|:---------------------------|:-----------------|:-------------------------|:-------------------------|:---------------------| +| :------------------------- | :--------------- | :----------------------- | :----------------------- | :------------------- | | 3.16 | 3.16 | 3.5, 3.4 | 2.13, 2.12 | 8 | | 3.15 | 3.15 | 3.5, 3.4 | 2.13, 2.12 | 8 | diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/design.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/design.mdx index f5608580..237091dc 100644 --- a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/design.mdx +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/design.mdx @@ -89,294 +89,16 @@ ScalarDB Analytics は様々なデータソースにわたって幅広いデー - `DURATION` - `INTERVAL` -### データソース別のカタログ情報マッピング +これらのデータ型はすべてのデータソースで使用され、異種データベースのクエリに統一された型システムを提供します。 -データソースを ScalarDB Analytics に登録する際、データソースのカタログ情報（名前空間、テーブル、列など）が解決され、ユニバーサルデータカタログに登録されます。データソースのカタログ情報を解決するために、データソース側の特定のオブジェクトがユニバーサルデータカタログオブジェクトにマッピングされます。このマッピングはカタログレベルのマッピングとデータ型マッピングの2つの部分で構成されています。以下のセクションでは、ScalarDB Analytics が各データソースからカタログレベルとデータ型をユニバーサルデータカタログにどのようにマッピングするかを説明します。 +### データソース統合 -#### カタログレベルのマッピング +データソースを ScalarDB Analytics に登録する際、2種類のマッピングが行われます： -カタログレベルのマッピングは、データソースから名前空間名、テーブル名、および列名をユニバーサルデータカタログへのマッピングです。各データソースでのカタログレベルのマッピングを確認するには、データソースを選択してください。 +1. **カタログ構造マッピング**: データソースのカタログ情報（名前空間、テーブル、列）が解決され、ユニバーサルデータカタログ構造にマッピングされます +2. **データ型マッピング**: 各データソースのネイティブデータ型が、上記のユニバーサルデータ型にマッピングされます - - - ScalarDB のカタログ情報は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： - - - ScalarDB 名前空間は名前空間にマッピングされます。したがって、ScalarDB データソースの名前空間は常に単一レベルで、名前空間名のみで設定されます。 - - ScalarDB テーブルはテーブルにマッピングされます。 - - ScalarDB 列は列にマッピングされます。 - - - - - PostgreSQL のカタログ情報は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： - - - PostgreSQL スキーマは名前空間にマッピングされます。したがって、PostgreSQL データソースの名前空間は常に単一レベルで、スキーマ名のみで設定されます。 - - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： - - `information_schema` - - `pg_catalog` - - PostgreSQL テーブルはテーブルにマッピングされます。 - - PostgreSQL 列は列にマッピングされます。 - - - - MySQL のカタログ情報は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： - - - MySQL データベースは名前空間にマッピングされます。したがって、MySQL データソースの名前空間は常に単一レベルで、データベース名のみで設定されます。 - - ユーザー定義データベースのみが名前空間にマッピングされます。以下のシステムデータベースは無視されます： - - `mysql` - - `sys` - - `information_schema` - - `performance_schema` - - MySQL テーブルはテーブルにマッピングされます。 - - MySQL 列は列にマッピングされます。 - - - - Oracle のカタログ情報は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： - - - Oracle スキーマは名前空間にマッピングされます。したがって、Oracle データソースの名前空間は常に単一レベルで、スキーマ名のみで設定されます。 - - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： - - `ANONYMOUS` - - `APPQOSSYS` - - `AUDSYS` - - `CTXSYS` - - `DBSNMP` - - `DGPDB_INT` - - `DBSFWUSER` - - `DVF` - - `DVSYS` - - `GGSYS` - - `GSMADMIN_INTERNAL` - - `GSMCATUSER` - - `GSMROOTUSER` - - `GSMUSER` - - `LBACSYS` - - `MDSYS` - - `OJVMSYS` - - `ORDDATA` - - `ORDPLUGINS` - - `ORDSYS` - - `OUTLN` - - `REMOTE_SCHEDULER_AGENT` - - `SI_INFORMTN_SCHEMA` - - `SYS` - - `SYS$UMF` - - `SYSBACKUP` - - `SYSDG` - - `SYSKM` - - `SYSRAC` - - `SYSTEM` - - `WMSYS` - - `XDB` - - `DIP` - - `MDDATA` - - `ORACLE_OCM` - - `XS$NULL` - - - - SQL Server のカタログ情報は ScalarDB Analytics によって自動的に解決されます。カタログレベルのオブジェクトは以下のようにマッピングされます： - - - SQL Server データベースとスキーマは共に名前空間にマッピングされます。したがって、SQL Server データソースの名前空間は常に二段階で、データベース名とスキーマ名で構成されます。 - - ユーザー定義データベースのみが名前空間にマッピングされます。以下のシステムデータベースは無視されます： - - `sys` - - `guest` - - `INFORMATION_SCHEMA` - - `db_accessadmin` - - `db_backupoperator` - - `db_datareader` - - `db_datawriter` - - `db_ddladmin` - - `db_denydatareader` - - `db_denydatawriter` - - `db_owner` - - `db_securityadmin` - - ユーザー定義スキーマのみが名前空間にマッピングされます。以下のシステムスキーマは無視されます： - - `master` - - `model` - - `msdb` - - `tempdb` - - SQL Server テーブルはテーブルにマッピングされます。 - - SQL Server 列は列にマッピングされます。 - - - - DynamoDB はスキーマレスであるため、DynamoDB データソースを登録する際に以下のような形式のJSONを使用してカタログ情報を明示的に指定する必要があります： - - ```json - { - "namespaces": [ - { - "name": "", - "tables": [ - { - "name": "", - "columns": [ - { - "name": "", - "type": "" - }, - ... - ] - }, - ... - ] - }, - ... - ] - } - ``` - - 指定した JSON では、任意の名前空間名を使用できますが、テーブル名は DynamoDB のテーブル名と一致する必要があり、列名と型は DynamoDB のフィールド名と型と一致する必要があります。 - - - - -#### データ型マッピング - -基盤となるデータソースのネイティブデータ型は ScalarDB Analytics のデータ型にマッピングされます。各データソースでのデータ型マッピングを確認するには、データソースを選択してください。 - - - - | **ScalarDB データ型** | **ScalarDB Analytics データ型** | - |:------------------------------|:---------------------------------| - | `BOOLEAN` | `BOOLEAN` | - | `INT` | `INT` | - | `BIGINT` | `BIGINT` | - | `FLOAT` | `FLOAT` | - | `DOUBLE` | `DOUBLE` | - | `TEXT` | `TEXT` | - | `BLOB` | `BLOB` | - | `DATE` | `DATE` | - | `TIME` | `TIME` | - | `TIMESTAMP` | `TIMESTAMP` | - | `TIMESTAMPTZ` | `TIMESTAMPTZ` | - - - | **PostgreSQL データ型** | **ScalarDB Analytics データ型** | - |:------------------------------|:---------------------------------| - | `integer` | `INT` | - | `bigint` | `BIGINT` | - | `real` | `FLOAT` | - | `double precision` | `DOUBLE` | - | `smallserial` | `SMALLINT` | - | `serial` | `INT` | - | `bigserial` | `BIGINT` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `text` | `TEXT` | - | `bpchar` | `TEXT` | - | `boolean` | `BOOLEAN` | - | `bytea` | `BLOB` | - | `date` | `DATE` | - | `time` | `TIME` | - | `time with time zone` | `TIME` | - | `time without time zone` | `TIME` | - | `timestamp` | `TIMESTAMP` | - | `timestamp with time zone` | `TIMESTAMPTZ` | - | `timestamp without time zone` | `TIMESTAMP` | - - - | **MySQL データ型** | **ScalarDB Analytics データ型** | - |:-----------------------|:---------------------------------| - | `bit` | `BOOLEAN` | - | `bit(1)` | `BOOLEAN` | - | `bit(x)` if *x >= 2* | `BLOB` | - | `tinyint` | `SMALLINT` | - | `tinyint(1)` | `BOOLEAN` | - | `boolean` | `BOOLEAN` | - | `smallint` | `SMALLINT` | - | `smallint unsigned` | `INT` | - | `mediumint` | `INT` | - | `mediumint unsigned` | `INT` | - | `int` | `INT` | - | `int unsigned` | `BIGINT` | - | `bigint` | `BIGINT` | - | `float` | `FLOAT` | - | `double` | `DOUBLE` | - | `real` | `DOUBLE` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `text` | `TEXT` | - | `binary` | `BLOB` | - | `varbinary` | `BLOB` | - | `blob` | `BLOB` | - | `date` | `DATE` | - | `time` | `TIME` | - | `datetime` | `TIMESTAMP` | - | `timestamp` | `TIMESTAMPTZ` | - - - | **Oracle データ型** | **ScalarDB Analytics データ型** | - |:-----------------------------------|:---------------------------------| - | `NUMBER` if *scale = 0* | `BIGINT` | - | `NUMBER` if *scale > 0* | `DOUBLE` | - | `FLOAT` if *precision ≤ 53* | `DOUBLE` | - | `BINARY_FLOAT` | `FLOAT` | - | `BINARY_DOUBLE` | `DOUBLE` | - | `CHAR` | `TEXT` | - | `NCHAR` | `TEXT` | - | `VARCHAR2` | `TEXT` | - | `NVARCHAR2` | `TEXT` | - | `CLOB` | `TEXT` | - | `NCLOB` | `TEXT` | - | `BLOB` | `BLOB` | - | `BOOLEAN` | `BOOLEAN` | - | `DATE` | `DATE` | - | `TIMESTAMP` | `TIMESTAMPTZ` | - | `TIMESTAMP WITH TIME ZONE` | `TIMESTAMPTZ` | - | `TIMESTAMP WITH LOCAL TIME ZONE` | `TIMESTAMP` | - | `RAW` | `BLOB` | - - - | **SQL Server データ型** | **ScalarDB Analytics データ型** | - |:---------------------------|:---------------------------------| - | `bit` | `BOOLEAN` | - | `tinyint` | `SMALLINT` | - | `smallint` | `SMALLINT` | - | `int` | `INT` | - | `bigint` | `BIGINT` | - | `real` | `FLOAT` | - | `float` | `DOUBLE` | - | `float(n)` if *n ≤ 24* | `FLOAT` | - | `float(n)` if *n ≥ 25* | `DOUBLE` | - | `binary` | `BLOB` | - | `varbinary` | `BLOB` | - | `char` | `TEXT` | - | `varchar` | `TEXT` | - | `nchar` | `TEXT` | - | `nvarchar` | `TEXT` | - | `ntext` | `TEXT` | - | `text` | `TEXT` | - | `date` | `DATE` | - | `time` | `TIME` | - | `datetime` | `TIMESTAMP` | - | `datetime2` | `TIMESTAMP` | - | `smalldatetime` | `TIMESTAMP` | - | `datetimeoffset` | `TIMESTAMPTZ` | - - - | **DynamoDB データ型** | **ScalarDB Analytics データ型** | - |:-------------------------|:---------------------------------| - | `Number` | `BYTE` | - | `Number` | `SMALLINT` | - | `Number` | `INT` | - | `Number` | `BIGINT` | - | `Number` | `FLOAT` | - | `Number` | `DOUBLE` | - | `Number` | `DECIMAL` | - | `String` | `TEXT` | - | `Binary` | `BLOB` | - | `Boolean` | `BOOLEAN` | - -:::warning - -ScalarDB Analytics に指定されたデータ型として `Number` 型のフィールド値が解析可能であることが必要です。例えば、`Number` 型のフィールドに対応する列が `INT` 型として指定されている場合、その値は整数でなければなりません。値が整数でない場合、クエリの実行時にエラーが発生します。 - -::: - - - +これらのマッピングにより、異なるデータベースシステム間での互換性と一貫性が確保されます。特定のデータベースがどのようにマッピングされるかの詳細については、管理ガイドの [カタログメタデータリファレンス](administration.mdx#カタログメタデータリファレンス) を参照してください。 ## クエリエンジン diff --git a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/run-analytical-queries.mdx b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/run-analytical-queries.mdx index 04d7a99f..211a934a 100644 --- a/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/run-analytical-queries.mdx +++ b/i18n/versioned_docs/ja-jp/docusaurus-plugin-content-docs/current/scalardb-analytics/run-analytical-queries.mdx @@ -4,12 +4,12 @@ tags: displayed_sidebar: docsJapanese --- -# ScalarDB Analytics を通じた分析クエリの実行 - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; import TranslationBanner from '/src/components/_translation-ja-jp.mdx'; +# ScalarDB Analytics を通じた分析クエリの実行 + このガイドでは、ScalarDB Analytics アプリケーションの開発方法について説明します。アーキテクチャと設計の詳細については、[ScalarDB Analytics の設計](./design.mdx)を参照してください。 @@ -22,7 +22,8 @@ ScalarDB Analytics は現在、実行エンジンとして Spark を使用し、 ### 前提条件 -ScalarDB Analytics は Apache Spark 3.4以降で動作します。まだ Spark をインストールしていない場合は、[Apache Spark のウェブサイト](https://spark.apache.org/downloads.html)から Spark ディストリビューションをダウンロードしてください。 +- **ScalarDB Analytics catalog server**: カタログメタデータを管理し、データソースに接続する実行中のインスタンス。サーバーには少なくとも1つのデータソースが登録されている必要があります。セットアップとデータソース登録の手順については、[ScalarDB Analytics catalog server のセットアップと管理](./administration.mdx)を参照してください。 +- **Apache Spark**: 互換性のあるバージョンの Apache Spark。サポートされているバージョンについては、[バージョン互換性](#バージョン互換性)を参照してください。まだ Spark をインストールしていない場合は、[Apache Spark のウェブサイト](https://spark.apache.org/downloads.html)から Spark ディストリビューションをダウンロードしてください。 :::note @@ -32,193 +33,63 @@ Apache Spark は Scala 2.12 または Scala 2.13 でビルドされています ### ScalarDB Analytics のセットアップのための Spark 設定 -以下のセクションでは、ScalarDB Analytics で利用可能なすべての設定オプションについて説明します。 - -- ScalarDB Analytics の Spark との統合方法 -- データソースの接続とアクセス方法 -- ライセンス情報の提供方法 - -実践的なシナリオでの設定例については、[サンプルアプリケーション設定](../scalardb-samples/scalardb-analytics-spark-sample/README.mdx#scalardb-analytics-の設定)を参照してください。 - -#### Spark プラグインの設定 - -| 設定キー名 | 必須 | 説明 | -|:-----------------------------------|:------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `spark.jars.packages` | いいえ | 必要な依存関係の Maven 座標をカンマ区切りで指定します。使用する ScalarDB Analytics パッケージを含める必要があります。含めない場合は、Spark アプリケーションの実行時にコマンドライン引数として指定します。ScalarDB Analytics の Maven 座標の詳細については、[ScalarDB Analytics 依存関係の追加](#scalardb-analytics-依存関係の追加)を参照してください。 | -| `spark.sql.extensions` | はい | `com.scalar.db.analytics.spark.extension.ScalarDbAnalyticsExtensions` を設定する必要があります。 | -| `spark.sql.catalog.` | はい | `com.scalar.db.analytics.spark.ScalarDbAnalyticsCatalog` を設定する必要があります。 | - -`` には任意の名前を指定できます。設定全体で同じカタログ名を使用するようにしてください。 - -#### ライセンスの設定 - -| 設定キー名 | 必須 | 説明 | -|:-----------------------------------------------------|:-----|:------------------------------------------------------------------------------------------------------------------------| -| `spark.sql.catalog..license.key` | はい | ScalarDB Analytics のライセンスキーの JSON 文字列 | -| `spark.sql.catalog..license.cert_pem` | はい | ScalarDB Analytics ライセンスの PEM エンコードされた証明書の文字列。`cert_pem` または `cert_path` のいずれかを設定する必要があります。 | -| `spark.sql.catalog..license.cert_path` | はい | ScalarDB Analytics ライセンスの PEM エンコードされた証明書へのパス。`cert_pem` または `cert_path` のいずれかを設定する必要があります。 | - -#### データソースの設定 - -ScalarDB Analytics は複数のタイプのデータソースをサポートしています。各タイプには特定の設定パラメータが必要です: - - - - -:::note - -ScalarDB Analytics は ScalarDB をデータソースとしてサポートしています。この表では、ScalarDB をデータソースとして設定する方法について説明します。 - -::: - -| 設定キー名 | 必須 | 説明 | -|:------------------------------------------------------------------------------|:-----|:----------------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `scalardb` を設定します | -| `spark.sql.catalog..data_source..config_path` | はい | ScalarDB の設定ファイルへのパス | - -:::tip - -`` には任意の名前を使用できます。 - -::: +ScalarDB Analytics は catalog server と統合するために特定の Spark 設定が必要です。 - - +#### 必要な Spark 設定 -| 設定キー名 | 必須 | 説明 | -|:---------------------------------------------------------------------------|:------|:-----------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `mysql` を設定します | -| `spark.sql.catalog..data_source..host` | はい | MySQL サーバーのホスト名 | -| `spark.sql.catalog..data_source..port` | はい | MySQL サーバーのポート番号 | -| `spark.sql.catalog..data_source..username` | はい | MySQL サーバーのユーザー名 | -| `spark.sql.catalog..data_source..password` | はい | MySQL サーバーのパスワード | -| `spark.sql.catalog..data_source..database` | いいえ | 接続するデータベースの名前 | +ScalarDB Analytics を Spark で使用するには、以下を設定する必要があります: -:::tip +1. **ScalarDB Analytics パッケージ**: Spark と Scala のバージョンに一致する JAR 依存関係を追加 +2. **メータリングリスナー**: 課金のためのリソース使用状況を追跡するリスナーを登録 +3. **カタログ登録**: ScalarDB Analytics サーバーに接続する Spark カタログを登録 -`` には任意の名前を使用できます。 +Spark を設定する際は、ScalarDB Analytics サーバー上で作成されたカタログと一致するカタログ名を指定する必要があります。これにより、Spark がそのカタログで管理されているデータソースに正しくアクセスできるようになります。 -::: - - - - -| 設定キー名 | 必須 | 説明 | -|:---------------------------------------------------------------------------|:-----|:---------------------------------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `postgresql` または `postgres` を設定します | -| `spark.sql.catalog..data_source..host` | はい | PostgreSQL サーバーのホスト名 | -| `spark.sql.catalog..data_source..port` | はい | PostgreSQL サーバーのポート番号 | -| `spark.sql.catalog..data_source..username` | はい | PostgreSQL サーバーのユーザー名 | -| `spark.sql.catalog..data_source..password` | はい | PostgreSQL サーバーのパスワード | -| `spark.sql.catalog..data_source..database` | はい | 接続するデータベースの名前 | - -:::tip +#### 設定例 -`` には任意の名前を使用できます。 +以下は完全な設定例です: -::: +```conf +# 1. ScalarDB Analytics パッケージ +spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-_: - - +# 2. メータリングリスナー +spark.extraListeners com.scalar.db.analytics.spark.metering.ScalarDbAnalyticsListener -| 設定キー名 | 必須 | 説明 | -|:-------------------------------------------------------------------------------|:-----|:------------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `oracle` を設定します | -| `spark.sql.catalog..data_source..host` | はい | Oracle サーバーのホスト名 | -| `spark.sql.catalog..data_source..port` | はい | Oracle サーバーのポート番号 | -| `spark.sql.catalog..data_source..username` | はい | Oracle サーバーのユーザー名 | -| `spark.sql.catalog..data_source..password` | はい | Oracle サーバーのパスワード | -| `spark.sql.catalog..data_source..service_name` | はい | Oracle サーバーのサービス名 | +# 3. カタログ登録 +spark.sql.catalog.myanalytics com.scalar.db.analytics.spark.catalog.ScalarDBAnalyticsCatalog +spark.sql.catalog.myanalytics.server.host analytics-server.example.com +spark.sql.catalog.myanalytics.server.catalog.port 11051 +spark.sql.catalog.myanalytics.server.metering.port 11052 +``` -:::tip +プレースホルダーを置き換えてください: -`` には任意の名前を使用できます。 +- ``: 使用している Spark のバージョン (例: `3.5` または `3.4`) +- ``: 使用している Scala のバージョン (例: `2.13` または `2.12`) +- ``: ScalarDB Analytics のバージョン (例: `3.16.0`) -::: +この例では: - - - -| 設定キー名 | 必須 | 説明 | -|:---------------------------------------------------------------------------|:-------|:--------------------------------------------------------------------------------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `sqlserver` または `mssql` を設定します | -| `spark.sql.catalog..data_source..host` | はい | SQL Server のホスト名 | -| `spark.sql.catalog..data_source..port` | はい | SQL Server のポート番号 | -| `spark.sql.catalog..data_source..username` | はい | SQL Server のユーザー名 | -| `spark.sql.catalog..data_source..password` | はい | SQL Server のパスワード | -| `spark.sql.catalog..data_source..database` | いいえ | 接続するデータベースの名前 | -| `spark.sql.catalog..data_source..secure` | いいえ | SQL Server への接続にセキュアな接続を使用するかどうか。セキュアな接続を使用する場合は `true` を設定します。 | +- カタログ名 `myanalytics` は、ScalarDB Analytics サーバー上に存在するカタログと一致する必要があります +- ScalarDB Analytics サーバーは `analytics-server.example.com` で実行されています +- テーブルには `myanalytics...
` の形式でアクセスします -:::tip +:::important -`` には任意の名前を使用できます。 +Spark 設定のカタログ名は、CLI を使用して ScalarDB Analytics サーバー上で作成されたカタログの名前と一致させる必要があります。たとえば、サーバー上で `production` という名前のカタログを作成した場合、Spark 設定プロパティでカタログ名として `production` を使用する必要があります（例：`spark.sql.catalog.production`、`spark.sql.catalog.production.server.host` など）。 ::: - - - -| 設定キー名 | 必須 | 説明 | -|:---------------------------------------------------------------------------|:--------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------| -| `spark.sql.catalog..data_source..type` | はい | 常に `dynamodb` を設定します | -| `spark.sql.catalog..data_source..region` | `region` または `endpoint` のいずれかを設定する必要があります | DynamoDB インスタンスの AWS リージョン | -| `spark.sql.catalog..data_source..endpoint` | `region` または `endpoint` のいずれかを設定する必要があります | DynamoDB インスタンスの AWS エンドポイント | -| `spark.sql.catalog..data_source..schema` | はい | カタログのスキーマを表す JSON オブジェクト。形式の詳細については、[カタログレベルのマッピング](./design.mdx#カタログレベルのマッピング)を参照してください。 | - -:::tip +:::note -`` には任意の名前を使用できます。 +データソース設定は catalog server で管理されます。catalog server でのデータソースの設定方法については、[ScalarDB Analytics catalog server のセットアップと管理](./administration.mdx#configure-data-sources)を参照してください。 ::: - - - -#### 設定例 - -以下は、複数のデータソースを持つ `scalardb` という名前のカタログを設定する ScalarDB Analytics の設定例です: - -```conf -# Sparkプラグインの設定 -spark.jars.packages com.scalar-labs:scalardb-analytics-spark-all-_: -spark.sql.extensions com.scalar.db.analytics.spark.extension.ScalarDbAnalyticsExtensions -spark.sql.catalog.scalardb com.scalar.db.analytics.spark.ScalarDbAnalyticsCatalog - -# ライセンスの設定 -spark.sql.catalog.scalardb.license.key -spark.sql.catalog.scalardb.license.cert_pem - -# データソースの設定 -spark.sql.catalog.scalardb.data_source.scalardb.type scalardb -spark.sql.catalog.scalardb.data_source.scalardb.config_path /path/to/scalardb.properties - -spark.sql.catalog.scalardb.data_source.mysql_source.type mysql -spark.sql.catalog.scalardb.data_source.mysql_source.host localhost -spark.sql.catalog.scalardb.data_source.mysql_source.port 3306 -spark.sql.catalog.scalardb.data_source.mysql_source.username root -spark.sql.catalog.scalardb.data_source.mysql_source.password password -spark.sql.catalog.scalardb.data_source.mysql_source.database mydb -``` - -括弧内の内容は以下のように変更する必要があります: +### Spark アプリケーションのビルド設定 -- ``: ScalarDB Analytics のライセンスキー -- ``: ScalarDB Analytics ライセンスの PEM エンコードされた証明書 -- ``: 使用している Spark のメジャーおよびマイナーバージョン (例: 3.4) -- ``: Spark インストールに対応する Scala のメジャーおよびマイナーバージョン (例: 2.12 または 2.13) -- ``: ScalarDB Analytics のバージョン - -### ScalarDB Analytics 依存関係の追加 - -ScalarDB Analytics は Maven Central Repository でホストされています。パッケージ名は `scalardb-analytics-spark-all-_:` で、以下の通りです: - -- ``: 使用している Spark のメジャーおよびマイナーバージョン (例: 3.4) -- ``: Spark インストールに対応する Scala のメジャーおよびマイナーバージョン (例: 2.12 または 2.13) -- ``: ScalarDB Analytics のバージョン - -バージョンの互換性の詳細については、[バージョン互換性](#バージョン互換性)を参照してください。 - -プロジェクトのビルド設定を設定することで、この依存関係をプロジェクトに追加できます。例えば、Gradle を使用している場合は、`build.gradle` ファイルに以下を追加できます: +ScalarDB Analytics を使用する Spark アプリケーションを開発する際は、ビルド設定に依存関係を追加できます。たとえば Gradle の場合: ```groovy dependencies { @@ -228,7 +99,7 @@ dependencies { :::note -Gradle の Shadow プラグインや Maven の Shade プラグインなどを使用して、アプリケーションを単一の fat JAR ファイルにバンドルする場合は、使用しているプラグインに応じて `provided` や `shadow` などの適切な configuration を選択して、fat JAR ファイルから ScalarDB Analytics を除外する必要があります。 +Gradle Shadow や Maven Shade などのプラグインを使用してアプリケーションを fat JAR にバンドルする場合は、`provided` や `shadow` などの設定を使用して fat JAR から ScalarDB Analytics を除外してください。 ::: @@ -248,7 +119,7 @@ ScalarDB Analytics を使用した Spark アプリケーションの開発には ::: -これらのすべての方法で、同じテーブル識別子形式を使用して ScalarDB Analytics のテーブルを参照できます。ScalarDB Analytics がデータソースからカタログ情報をマッピングする方法の詳細については、[データソース別のカタログ情報マッピング](./design.mdx#データソース別のカタログ情報マッピング)を参照してください。 +これらのすべての方法で、同じテーブル識別子形式を使用して ScalarDB Analytics のテーブルを参照できます。ScalarDB Analytics がデータソースからカタログ情報をマッピングする方法の詳細については、[カタログメタデータリファレンス](./administration.mdx#catalog-metadata-reference)を参照してください。 @@ -369,13 +240,9 @@ ScalarDB Analytics は、データソース、名前空間、テーブル、列 データソース内の情報が ScalarDB Analytics カタログにマッピングされる方法の詳細については、[データソース別のカタログ情報マッピング](./design.mdx#データソース別のカタログ情報マッピング)を参照してください。 -### カタログレベルのマッピング - -ScalarDB Analytics カタログの各カタログレベルオブジェクトは、Spark カタログにマッピングされます。以下の表は、カタログレベルがどのようにマッピングされるかを示しています: +### カタログ構造のマッピング -#### データソーステーブル - -ScalarDB Analytics カタログのデータソースのテーブルは、Spark テーブルにマッピングされます。ScalarDB Analytics テーブルに対応する Spark テーブルの識別子には以下の形式が使用されます: +ScalarDB Analytics は、データソースからのカタログ構造を Spark カタログにマッピングします。ScalarDB Analytics カタログのデータソースのテーブルは、Spark テーブルにマッピングされ、以下の形式で識別されます: ```console ... @@ -390,33 +257,6 @@ ScalarDB Analytics カタログのデータソースのテーブルは、Spark 例えば、`my_catalog` という名前の ScalarDB カタログに、`my_data_source` という名前のデータソースと `my_schema` という名前のスキーマがある場合、そのスキーマ内の `my_table` という名前のテーブルを `my_catalog.my_data_source.my_schema.my_table` として参照できます。 -#### ビュー - -ScalarDB Analytics のビューは、ビューではなく Spark カタログのテーブルとして提供されます。ScalarDB Analytics ビューに対応する Spark テーブルの識別子には以下の形式が使用されます: - -```console -.view.. -``` - -括弧内の内容は以下の通りです: - -- ``: カタログの名前 -- ``: ビュー名前空間の名前。ビュー名前空間が複数レベルある場合は、ドット (`.`) で区切って連結されます -- ``: ビューの名前 - -例えば、`my_catalog` という名前の ScalarDB カタログと `my_view_namespace` という名前のビュー名前空間がある場合、その名前空間内の `my_view` という名前のビューを `my_catalog.view.my_view_namespace.my_view` として参照できます。 - -:::note - -データソーステーブル識別子との競合を避けるため、`view` が接頭辞として付けられます。 - -::: - -##### WAL 解釈ビュー - -[ScalarDB Analytics の設計](./design.mdx)で説明されているように、ScalarDB Analytics は WAL 解釈ビューと呼ばれる特別なタイプのビューを提供します。これらのビューは、ScalarDB データソースのテーブルに対して自動的に作成され、テーブル内の WAL メタデータを解釈することでユーザーフレンドリーなビューを提供します。 - -元の ScalarDB テーブルのデータソース名と名前空間の名前が WAL 解釈ビューのビュー名前空間の名前として使用されるため、`my_data_source` という名前のデータソースの `my_namespace` という名前の名前空間にある `my_table` という名前の ScalarDB テーブルがある場合、そのテーブルの WAL 解釈ビューを `my_catalog.view.my_data_source.my_namespace.my_table` として参照できます。 ### データ型マッピング From e644937dbfdc2154cc7788da1e29e905ac7abd8a Mon Sep 17 00:00:00 2001 From: Josh Wong <23216828+josh-wong@users.noreply.github.com> Date: Wed, 6 Aug 2025 18:37:51 +0900 Subject: [PATCH 3/4] Add ScalarDB Analytics admin guide and config reference --- sidebars.js | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/sidebars.js b/sidebars.js index f1cb4ae4..411c01ef 100644 --- a/sidebars.js +++ b/sidebars.js @@ -515,6 +515,16 @@ const sidebars = { id: 'scalardb-analytics-postgresql/schema-importer', label: 'PostgreSQL Schema Importer for PostgreSQL', }, + { + type: 'doc', + id: 'scalardb-analytics/administration', + label: 'Manage ScalarDB Analytics', + }, + { + type: 'doc', + id: 'scalardb-analytics/configuration', + label: 'Configuration Reference', + }, ], }, { @@ -1472,6 +1482,16 @@ const sidebars = { id: 'scalardb-analytics-postgresql/schema-importer', label: 'PostgreSQL 用 Schema Importer', }, + { + type: 'doc', + id: 'scalardb-analytics/administration', + label: 'ScalarDB Analytics を管理', + }, + { + type: 'doc', + id: 'scalardb-analytics/configuration', + label: '設定リファレンス', + }, ], }, { From 6e12a8ff656172f9869905c5e2c6a44c127f2927 Mon Sep 17 00:00:00 2001 From: Josh Wong <23216828+josh-wong@users.noreply.github.com> Date: Wed, 6 Aug 2025 18:37:30 +0900 Subject: [PATCH 4/4] Add redirect for ScalarDB Analytics quickstart --- docusaurus.config.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index 50b1ac47..8c6b0bad 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -186,6 +186,10 @@ const config = { to: '/docs/latest/releases/release-support-policy', from: '/docs/releases/release-support-policy', }, + { + to: '/docs/latest/scalardb-analytics/quickstart', + from: '/docs/latest/scalardb-samples/scalardb-analytics-spark-sample', + }, { to: '/docs/latest/scalardb-analytics/run-analytical-queries', from: '/docs/latest/scalardb-analytics/deployment/development',