Analyze file data in ApsaraDB for SelectDB - ApsaraDB for SelectDB

Amazon S3 TVF

s3(), herhangi bir S3 uyumlu nesne depolama sisteminden dosyaları okur. Desteklenen biçimler: CSV, csv_with_names, csv_with_names_and_types, JSON, Parquet ve ORC.

Söz dizimi

s3(
  "uri"           = "<uri>",
  "s3.access_key" = "<access-key>",
  "s3.secret_key" = "<secret-key>",
  "s3.region"     = "<region>",
  "format"        = "<format>"
  [, "s3.session_token" = "<session-token>"]
  [, "use_path_style"   = "true|false"]
  [, "keyn"             = "valuen" ...]
)

Zorunlu parametreler köşeli parantez olmadan listelenir. İsteğe bağlı parametreler [...] içine alınır.

Parametreler

Her parametre, "anahtar" = "değer" biçiminde bir anahtar-değer çiftidir.

Zorunlu parametreler

Parametre	Açıklama
`uri`	Amazon S3'e erişmek için kullanılan URI. Desteklenen şemalar: `http://`, `https://` ve `s3://`. URI ile eşleşen dosya yoksa veya eşleşen tüm dosyalar boşsa TVF boş bir sonuç kümesi döndürür.
`s3.access_key`	Erişim anahtarı kimliği.
`s3.secret_key`	Gizli erişim anahtarı.
`s3.region`	Amazon S3 bölgesi. Varsayılan: `us-east-1`.
`format`	Dosya biçimi. Geçerli değerler: `csv`, `csv_with_names`, `csv_with_names_and_types`, `json`, `parquet`, `orc`.

İsteğe bağlı parametreler

Parametre	Varsayılan	Açıklama
`s3.session_token`	—	Geçici oturum belirteci. Geçici oturum kimlik doğrulaması etkinleştirildiğinde gereklidir.
`use_path_style`	`false`	Sanal barındırılan stil yerine yol stilinin kullanılıp kullanılmayacağını kontrol eder. Sanal barındırılan stili desteklemeyen depolama sistemleri (örneğin MinIO) için `true` olarak ayarlayın. Not URI `s3://` şemasını kullanıyorsa bu ayardan bağımsız olarak her zaman sanal barındırılan stil kullanılır.
`column_separator`	`,`	Sütun sınırlayıcısı.
`line_delimiter`	`\n`	Satır sınırlayıcısı.
`compress_type`	`unknown`	Sıkıştırma türü. `unknown` değeri türü URI son ekinden otomatik olarak çıkarır. Diğer geçerli değerler: `plain`, `gz`, `lzo`, `bz2`, `lz4frame`, `deflate`.
`read_json_by_line`	`true`	JSON verilerini satır satır okur.
`num_as_string`	`false`	Sayısal değerleri dize olarak işler.
`fuzzy_parse`	`false`	JSON içe aktarma performansını hızlandırır.
`jsonpaths`	—	JSON verilerinden çıkarılacak alanlar. Biçim: `jsonpaths: ["$.k2", "$.k1"]`.
`strip_outer_array`	`false`	Üst düzey bir JSON dizisini birden çok satır olarak ele alır; her satırda bir öğe bulunur. Biçim: `strip_outer_array: true`.
`json_root`	(boş)	JSON ayrıştırma için kök düğüm. ApsaraDB for SelectDB yalnızca bu düğüm altındaki öğeleri çıkarır ve ayrıştırır. Biçim: `json_root: $.RECORDS`.
`path_partition_keys`	—	Dosya yoluna gömülü, virgülle ayrılmış bölüm anahtarı sütun adları. Örneğin `/path/to/city=beijing/date=2023-07-09` yolu için bunu `city,date` olarak ayarlayın. ApsaraDB for SelectDB veri içe aktarma sırasında ilgili sütun adlarını ve sütun değerlerini yoldan okur.

Örnekler

MinIO uyumlu bir depolama sisteminden CSV dosyası okuma

MinIO varsayılan olarak yol stilini kullandığından use_path_style parametresini true olarak ayarlayın:

SELECT * FROM s3(
    "uri"           = "http://127.0.0.1:9312/test2/student1.csv",
    "s3.access_key" = "minioadmin",
    "s3.secret_key" = "minioadmin",
    "format"        = "csv",
    "use_path_style"= "true")
ORDER BY c1;

Object Storage Service (OSS) üzerinden Parquet dosyası okuma

OSS sanal barındırılan stil gerektirir. use_path_style parametresini false olarak ayarlayın:

SELECT * FROM s3(
    "uri"           = "http://example-bucket.oss-cn-beijing.aliyuncs.com/your-folder/file.parquet",
    "s3.access_key" = "ak",
    "s3.secret_key" = "sk",
    "format"        = "parquet",
    "use_path_style"= "false");

Yol stili kullanarak CSV dosyası okuma

use_path_style parametresi true olduğunda paket adı URI yolunun bir parçasıdır:

SELECT * FROM s3(
    "uri"           = "https://endpoint/bucket/file/student.csv",
    "s3.access_key" = "ak",
    "s3.secret_key" = "sk",
    "format"        = "csv",
    "use_path_style"= "true");

Sanal barındırılan stil kullanarak CSV dosyası okuma

use_path_style parametresi false olduğunda paket adı ana bilgisayar adının bir parçasıdır:

SELECT * FROM s3(
    "uri"           = "https://bucket.endpoint/bucket/file/student.csv",
    "s3.access_key" = "ak",
    "s3.secret_key" = "sk",
    "format"        = "csv",
    "use_path_style"= "false");

HDFS TVF

hdfs(), HDFS'den dosyaları s3() fonksiyonunun nesne depolamadan okumasına benzer şekilde okur. Desteklenen biçimler: CSV, csv_with_names, csv_with_names_and_types, JSON, Parquet ve ORC.

Söz dizimi

hdfs(
  "uri"              = "<uri>",
  "fs.defaultFS"     = "<hostname:port>",
  "hadoop.username"  = "<username>",
  "format"           = "<format>"
  [, "hadoop.security.authentication" = "Simple|Kerberos"]
  [, "keyn"                           = "valuen" ...]
)

Parametreler

Zorunlu parametreler

Parametre	Açıklama
`uri`	HDFS'e erişmek için kullanılan URI. URI ile eşleşen dosya yoksa veya eşleşen tüm dosyalar boşsa TVF boş bir sonuç kümesi döndürür.
`fs.defaultFS`	HDFS NameNode'un ana bilgisayar adı ve bağlantı noktası.
`hadoop.username`	HDFS erişimi için kullanılan kullanıcı adı. Boş olamaz.
`format`	Dosya biçimi. Geçerli değerler: `csv`, `csv_with_names`, `csv_with_names_and_types`, `json`, `parquet`, `orc`.

İsteğe bağlı parametreler

Parametre	Varsayılan	Açıklama
`hadoop.security.authentication`	—	Kimlik doğrulama yöntemi. Geçerli değerler: `Simple`, `Kerberos`.
`hadoop.kerberos.principal`	—	Kerberos asıl adı. Kerberos kimlik doğrulaması etkinleştirildiğinde gereklidir.
`hadoop.kerberos.keytab`	—	Kerberos keytab dosyasının yolu. Kerberos kimlik doğrulaması etkinleştirildiğinde gereklidir.
`dfs.client.read.shortcircuit`	—	Yerel HDFS verileri için kısa devre okumalarını etkinleştirir (BOOLEAN).
`dfs.domain.socket.path`	—	DataNode istemci iletişimi için UNIX etki alanı soket yolu. Yoldaki `_PORT` dizesi DataNode TCP bağlantı noktası ile değiştirilir.
`dfs.nameservices`	—	Ad hizmetlerinin mantıksal adları. `core-site.xml` içindeki `dfs.nameservices` ile eşleşir.
`dfs.ha.namenodes.<nameservice>`	—	NameNode'ların mantıksal adları. Hadoop yüksek kullanılabilirlik (HA) dağıtımları için gereklidir.
`dfs.namenode.rpc-address.<nameservice>.<namenode>`	—	NameNode'un dinlediği HTTP URL'si. Hadoop HA dağıtımları için gereklidir.
`dfs.client.failover.proxy.provider.<nameservice>`	—	HA istemci bağlantıları için yük devretme proxy sağlayıcı uygulama sınıfı. Hadoop HA dağıtımları için gereklidir.
`read_json_by_line`	`true`	JSON verilerini satır satır okur.
`num_as_string`	`false`	Sayısal değerleri dize olarak işler.
`fuzzy_parse`	`false`	JSON içe aktarma performansını hızlandırır.
`jsonpaths`	—	JSON verilerinden çıkarılacak alanlar. Biçim: `jsonpaths: ["$.k2", "$.k1"]`.
`strip_outer_array`	`false`	Üst düzey bir JSON dizisini birden çok satır olarak ele alır; her satırda bir öğe bulunur. Biçim: `strip_outer_array: true`.
`json_root`	(boş)	JSON ayrıştırma için kök düğüm. Biçim: `json_root: $.RECORDS`.
`trim_double_quotes`	`false`	CSV dosyalarındaki her alandan en dıştaki çift tırnak işaretlerini kırpır.
`skip_lines`	`0`	CSV dosyalarında atlanacak baştaki satır sayısı. Aralık: `[0–Integer.MaxValue]`. `format` parametresi `csv_with_names` veya `csv_with_names_and_types` olduğunda etkisi yoktur.
`path_partition_keys`	—	Dosya yoluna gömülü, virgülle ayrılmış bölüm anahtarı sütun adları. S3 TVF ile aynı davranışı sergiler.

Örnekler

HDFS'den CSV dosyası okuma

SELECT * FROM hdfs(
    "uri"              = "hdfs://127.0.0.1:842/user/doris/csv_format_test/student.csv",
    "fs.defaultFS"     = "hdfs://127.0.0.1:8424",
    "hadoop.username"  = "doris",
    "format"           = "csv");

-- Sample response
+------+---------+------+
| c1   | c2      | c3   |
+------+---------+------+
| 1    | alice   | 18   |
| 2    | bob     | 20   |
| 3    | jack    | 24   |
| 4    | jackson | 19   |
| 5    | liming  | 18   |
+------+---------+------+

HA modunda HDFS'den CSV dosyası okuma

Hadoop HA dağıtımları için üç HA'ya özel parametre ekleyin:

SELECT * FROM hdfs(
    "uri"                                         = "hdfs://127.0.0.1:842/user/doris/csv_format_test/student.csv",
    "fs.defaultFS"                                = "hdfs://127.0.0.1:8424",
    "hadoop.username"                             = "doris",
    "format"                                      = "csv",
    "dfs.nameservices"                            = "my_hdfs",
    "dfs.ha.namenodes.my_hdfs"                   = "nn1,nn2",
    "dfs.namenode.rpc-address.my_hdfs.nn1"       = "nanmenode01:8020",
    "dfs.namenode.rpc-address.my_hdfs.nn2"       = "nanmenode02:8020",
    "dfs.client.failover.proxy.provider.my_hdfs" = "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider");

-- Sample response
+------+---------+------+
| c1   | c2      | c3   |
+------+---------+------+
| 1    | alice   | 18   |
| 2    | bob     | 20   |
| 3    | jack    | 24   |
| 4    | jackson | 19   |
| 5    | liming  | 18   |
+------+---------+------+

Dosyaları sorgulama ve analiz etme

Bu bölümdeki tüm örnekler Amazon S3 TVF'yi kullanır. Aynı kalıplar HDFS TVF için de geçerlidir.

Dosya şemasını inceleme

Bir dosyayı sorgulamadan önce şemasını incelemek için DESC FUNCTION komutunu kullanın. ApsaraDB for SelectDB, Parquet, ORC, CSV ve JSON dosyaları için sütun türlerini otomatik olarak tahmin eder.

DESC FUNCTION s3(
    "uri"            = "http://127.0.0.1:9312/test2/test.snappy.parquet",
    "s3.access_key"  = "ak",
    "s3.secret_key"  = "sk",
    "format"         = "parquet",
    "use_path_style" = "true");

-- Sample response
+---------------+--------------+------+-------+---------+-------+
| Field         | Type         | Null | Key   | Default | Extra |
+---------------+--------------+------+-------+---------+-------+
| p_partkey     | INT          | Yes  | false | NULL    | NONE  |
| p_name        | TEXT         | Yes  | false | NULL    | NONE  |
| p_mfgr        | TEXT         | Yes  | false | NULL    | NONE  |
| p_brand       | TEXT         | Yes  | false | NULL    | NONE  |
| p_type        | TEXT         | Yes  | false | NULL    | NONE  |
| p_size        | INT          | Yes  | false | NULL    | NONE  |
| p_container   | TEXT         | Yes  | false | NULL    | NONE  |
| p_retailprice | DECIMAL(9,0) | Yes  | false | NULL    | NONE  |
| p_comment     | TEXT         | Yes  | false | NULL    | NONE  |
+---------------+--------------+------+-------+---------+-------+

CSV dosyaları için tüm sütunlar varsayılan olarak STRING olarak tahmin edilir. Sütun adlarını ve türlerini açıkça belirtmek için csv_schema parametresini name1:type1;name2:type2;... biçimiyle kullanın:

SELECT * FROM s3(
    "uri"              = "https://bucket1/inventory.dat",
    "s3.access_key"    = "ak",
    "s3.secret_key"    = "sk",
    "format"           = "csv",
    "column_separator" = "|",
    "csv_schema"       = "k1:int;k2:int;k3:int;k4:decimal(38,10)",
    "use_path_style"   = "true");

Belirtilen bir tür gerçek verilerle uyuşmazsa veya dosyada bulunanlardan daha fazla sütun belirtirseniz ApsaraDB for SelectDB bu sütunlar için NULL döndürür.

csv_schema içinde aşağıdaki sütun türleri desteklenir:

Belirtilen tür	Eşlenen tür
`tinyint`	tinyint
`smallint`	smallint
`int`	int
`bigint`	bigint
`largeint`	largeint
`float`	float
`double`	double
`decimal(p,s)`	decimalv3(p,s)
`date`	datev2
`datetime`	datetimev2
`char`	string
`varchar`	string
`string`	string
`boolean`	boolean

SQL sorguları çalıştırma

TVF'yi SQL'de bir tablo adının geçerli olduğu her yerde kullanabilirsiniz; buna FROM yan tümceleri ve ortak tablo ifadeleri (CTE'ler) dahildir:

SELECT * FROM s3(
    "uri"            = "http://127.0.0.1:9312/test2/test.snappy.parquet",
    "s3.access_key"  = "ak",
    "s3.secret_key"  = "sk",
    "format"         = "parquet",
    "use_path_style" = "true")
LIMIT 5;

-- Sample response
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
| p_partkey | p_name                                   | p_mfgr         | p_brand  | p_type                  | p_size | p_container | p_retailprice | p_comment           |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+
|         1 | goldenrod lavender spring chocolate lace | Manufacturer#1 | Brand#13 | PROMO BURNISHED COPPER  |      7 | JUMBO PKG   |           901 | ly. slyly ironi     |
|         2 | blush thistle blue yellow saddle         | Manufacturer#1 | Brand#13 | LARGE BRUSHED BRASS     |      1 | LG CASE     |           902 | lar accounts amo    |
|         3 | spring green yellow purple cornsilk      | Manufacturer#4 | Brand#42 | STANDARD POLISHED BRASS |     21 | WRAP CASE   |           903 | egular deposits hag |
|         4 | cornflower chocolate smoke green pink    | Manufacturer#3 | Brand#34 | SMALL PLATED BRASS      |     14 | MED DRUM    |           904 | p furiously r       |
|         5 | forest brown coral puff cream            | Manufacturer#3 | Brand#32 | STANDARD POLISHED TIN   |     15 | SM PKG      |           905 |  wake carefully     |
+-----------+------------------------------------------+----------------+----------+-------------------------+--------+-------------+---------------+---------------------+

Görünüm oluşturma

Her sorguda kimlik bilgilerini açığa çıkarmadan erişimi paylaşmak ve izinleri yönetmek için bir TVF üzerinde görünüm oluşturun:

CREATE VIEW v1 AS
SELECT * FROM s3(
    "uri"            = "http://127.0.0.1:9312/test2/test.snappy.parquet",
    "s3.access_key"  = "ak",
    "s3.secret_key"  = "sk",
    "format"         = "parquet",
    "use_path_style" = "true");

DESC v1;

SELECT * FROM v1;

GRANT SELECT_PRIV ON db1.v1 TO user1;

Dosya verilerini bir tabloya içe aktarma

Dosya verilerini bir ApsaraDB for SelectDB tablosuna yüklemek için bir TVF ile INSERT INTO SELECT komutunu kullanın:

-- Step 1: Create a target table.
CREATE TABLE IF NOT EXISTS test_table
(
    id   INT,
    name VARCHAR(50),
    age  INT
)
DISTRIBUTED BY HASH(id) BUCKETS 4
PROPERTIES("replication_num" = "1");

-- Step 2: Insert data from the S3 file.
INSERT INTO test_table (id, name, age)
SELECT CAST(id AS INT) AS id, name, CAST(age AS INT) AS age
FROM s3(
    "uri"            = "http://127.0.0.1:9312/test2/test.snappy.parquet",
    "s3.access_key"  = "ak",
    "s3.secret_key"  = "sk",
    "format"         = "parquet",
    "use_path_style" = "true");

Kullanım notları

Boş URI veya eşleşen dosya olmaması: URI mevcut değilse veya eşleşen tüm dosyalar boşsa TVF boş bir sonuç kümesi döndürür. Bu durumda DESC FUNCTION komutunu çalıştırmak yoksayılabilecek sahte bir __dummy_col sütunu döndürür.
CSV dosyalarında boş ilk satır: Dosya biçimi CSV ise ve dosya boş değil ancak ilk satır boşsa şu hata döndürülür: The first line is empty, can not parse column numbers. CSV dosyanızın ilk satırının boş olmadığından emin olun.
CSV şemasında tür uyuşmazlıkları: csv_schema ile sütun türleri belirttiğinizde ve bir değer bildirilen türle eşleşmediğinde (örneğin INT olarak bildirilen bir sütunda dize değeri varsa) ApsaraDB for SelectDB hata vermek yerine o değer için NULL döndürür.