add doc of stage-datalink

matrixorigin · Nov 7, 2024 · aa6c211 · aa6c211
1 parent 3d25b11
commit aa6c211
Show file tree

Hide file tree

Showing 2 changed files with 142 additions and 0 deletions.
diff --git a/docs/MatrixOne/Develop/data-integration/stage-datalink.md b/docs/MatrixOne/Develop/data-integration/stage-datalink.md
@@ -0,0 +1,140 @@
+# Stage
+
+在 MatrixOne，**Stage** 用于连接外部存储位置（如 AWS S3、MINIO 或文件系统），从而支持数据文件的批量导入、导出以及管理。**DATALINK** 则是一种数据类型，用于引用和访问外部存储上的数据文件，使得数据库能够直接关联外部资源，而无需将文件内容直接存储在数据库内。这种结构化管理不仅减少了数据库存储需求，还提供了灵活的数据访问方式。
+
+将外部 Stage 与 DATALINK 结合使用，可以实现数据文件的高效管理和处理。通过这种组合方式，平台可以更轻松地存储、加载大数据量的外部文件，如数据集和模型文件，并为各种分析和处理任务提供持续的文件更新支持。这对于需要快速访问和动态更新的场景尤其有帮助，例如定期的数据分析、模型训练和实时数据处理等。
+
+## 应用场景
+
+stage 和 datalink 的使用场景非常广泛，尤其适合大规模数据处理、分析以及模型训练等需求较高的应用场景。以下是一些典型应用场景：
+
+- **数据集管理与处理**：在日常数据处理和分析工作中，大型数据集往往存储在外部存储上，如 AWS S3。通过外部 Stage，平台能够轻松配置并访问这些数据源，同时利用 DATALINK 数据类型直接引用和读取文件位置，无需将数据导入数据库。这样可以节省数据库存储，快速加载数据集，便于数据科学家进行数据清理、预处理等工作。
+
+- **机器学习模型训练和更新**：随着数据变化，机器学习模型需要频繁更新以保证预测准确性。在这种情况下，外部 Stage 可用于存储训练数据集和模型文件，并通过 DATALINK 快速引用模型文件。训练新模型时，可以直接从外部存储加载最新数据，同时将训练好的模型版本保存在外部位置，以便随时加载并在生产环境中使用。
+
+- **多媒体文件管理与分析**：在管理大量图片、音频、视频等多媒体文件的业务中，直接存储在数据库内会导致存储成本高、效率低。利用外部 Stage 和 DATALINK，可以将多媒体文件存储在外部系统，并通过 DATALINK 引用，实现文件的灵活存取。这对于需要动态访问大量文件、进行内容分析或媒体推荐的场景非常有用。
+
+- **日志和审计文件的长期存储与查询**：日志数据和审计文件通常需要长期存储以满足合规需求，但直接存储在数据库中会导致占用大量空间。通过外部 Stage 和 DATALINK，将日志文件存储在外部系统中，并按需引用和查询，可以有效降低存储压力，提升查询效率，并满足审计需求。
+
+- **定期报告和数据备份**：业务运营中，定期生成的报告和备份文件可以存储在外部存储上，通过 DATALINK 引用，便于访问与管理。这样不仅简化了数据备份和恢复操作，还为数据的历史追溯提供支持。
+
+这些场景展示了外部 Stage 与 DATALINK 结合在数据管理中的灵活性和高效性。利用这种方法，企业能够以更低的成本实现对大数据文件的高效管理与访问，为数据处理和分析提供强大的支持。
+
+## 示例
+
+某电商平台每天生成大量订单数据，记录用户的购买情况、产品信息、付款状态等。为了提升销售预测、用户行为分析等，平台每天将订单数据保存为 CSV 文件，并上传到 MatrixOne 的外部 Stage，供数据分析和机器学习模型使用。
+
+### 操作步骤
+
+#### 在 S3 上创建存储桶
+
+在这里，我们以 AWS S3 为例，创建名为 `orders-bucket` 的存储桶，将每日生成的订单文件上传至 S3。
+
+#### 创建 Stage
+
+首先，在 MatrixOne 中创建外部 Stage 指向 S3 上的数据存储位置。
+
+```sql
+create stage stage01 url = 's3://orders-bucket/test' credentials = {"aws_key_id"='xxxx',"aws_secret_key"='xxxx',"AWS_REGION"='us-west-2','PROVIDER'='Amazon', 'ENDPOINT'='s3.us-west-2.amazonaws.com'};
+
+mysql> select * from stage_list('stage://stage01') as f;
++-----------------------------+
+| file                        |
++-----------------------------+
+| /test/orders_2023_11_06.csv |
++-----------------------------+
+1 row in set (0.01 sec)
+```
+
+#### 创建表管理数据集文件
+
+创建一张 order_documents 表，用于记录 csv 文件的元数据，使用 DATALINK 字段来存储文件路径。DATALINK 使得文件存储和访问更加高效，可以在数据导入前先进行文件内容的检查和预处理，从而确保数据质量。此外，DATALINK 还支持多源数据的集成，使得跨系统的文件数据引用更加便捷，避免了将文件数据直接加载到数据库中，减少了存储压力并提高了数据处理的灵活性。
+
+```sql
+CREATE TABLE order_documents (
+    document_id INT AUTO_INCREMENT,
+    file_link DATALINK                     -- csv 文件链接
+);
+
+INSERT INTO order_documents (file_link) VALUES 
+    ('stage://stage01/orders_2023_11_06.csv');
+
+select document_id,load_file(file_link) from order_documents;
+mysql> select document_id,load_file(file_link) from order_documents;
++-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| document_id | load_file(file_link)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
++-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+|           1 | OrderID,UserID,ProductID,Quantity,TotalAmount,PaymentStatus,OrderDate
+1001,123,2001,2,49.99,Completed,2023-11-06
+1002,124,2002,1,19.99,Pending,2023-11-06
+1003,125,2003,3,29.97,Completed,2023-11-06
+1004,126,2001,1,24.99,Cancelled,2023-11-06
+1005,127,2004,4,79.96,Completed,2023-11-06
+1006,128,2005,2,39.98,Completed,2023-11-06
+1007,129,2006,1,15.99,Pending,2023-11-06
+1008,130,2002,2,39.98,Completed,2023-11-06
+1009,131,2007,1,9.99,Completed,2023-11-06
+1010,132,2008,5,49.95,Completed,2023-11-06
+
+ |
++-------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+1 row in set (0.03 sec)
+```
+
+#### 加载数据到表中
+
+每日订单上传后，可以使用以下 SQL 语句，将数据加载到 MatrixOne 的订单表 orders 中，以便进一步分析和查询。
+
+```sql
+
+CREATE TABLE orders (
+    OrderID INT,
+    UserID INT,
+    ProductID INT,
+    Quantity INT,
+    TotalAmount DECIMAL(10, 2),
+    PaymentStatus VARCHAR(20),
+    OrderDate DATE
+);
+
+mysql> load data infile 'stage://stage01/orders_2023_11_06.csv' into table orders fields terminated by ',' ignore 1 lines;
+Query OK, 10 rows affected (0.56 sec)
+
+mysql> select * from orders;
++---------+--------+-----------+----------+-------------+---------------+------------+
+| orderid | userid | productid | quantity | totalamount | paymentstatus | orderdate  |
++---------+--------+-----------+----------+-------------+---------------+------------+
+|    1001 |    123 |      2001 |        2 |       49.99 | Completed     | 2023-11-06 |
+|    1002 |    124 |      2002 |        1 |       19.99 | Pending       | 2023-11-06 |
+|    1003 |    125 |      2003 |        3 |       29.97 | Completed     | 2023-11-06 |
+|    1004 |    126 |      2001 |        1 |       24.99 | Cancelled     | 2023-11-06 |
+|    1005 |    127 |      2004 |        4 |       79.96 | Completed     | 2023-11-06 |
+|    1006 |    128 |      2005 |        2 |       39.98 | Completed     | 2023-11-06 |
+|    1007 |    129 |      2006 |        1 |       15.99 | Pending       | 2023-11-06 |
+|    1008 |    130 |      2002 |        2 |       39.98 | Completed     | 2023-11-06 |
+|    1009 |    131 |      2007 |        1 |        9.99 | Completed     | 2023-11-06 |
+|    1010 |    132 |      2008 |        5 |       49.95 | Completed     | 2023-11-06 |
++---------+--------+-----------+----------+-------------+---------------+------------+
+10 rows in set (0.01 sec)
+```
+
+#### 卸载数据到 satge
+
+假如商家需要将每日的订单数据从 orders 表导出到外部存储系统（如 AWS S3）以进行备份、共享或与合作伙伴共享数据。我们也可以通过将数据卸载到 stage 中实现。
+
+```sql
+--创建指向外部存储系统的 satge02
+create stage stage02 url = 's3://order-share-bucket/' credentials = {"aws_key_id"='xxxx',"aws_secret_key"='xxxx',"AWS_REGION"='us-west-2','PROVIDER'='Amazon', 'ENDPOINT'='s3.us-west-2.amazonaws.com'};
+
+--将 order 表中数据卸载到 satge02
+select * from orders into outfile 'stage://stage02/order_share.csv';
+
+--可以看到，数据卸载成功
+mysql> select * from stage_list('stage://stage02') as f;
++------------------+
+| file             |
++------------------+
+| /order_share.csv |
++------------------+
+1 row in set (0.01 sec)
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -140,6 +140,8 @@ nav:
       - 数据去重:
          - COUNT(DISTINCT): MatrixOne/Develop/distinct-data/count-distinct.md
          - BITMAP: MatrixOne/Develop/distinct-data/bitmap.md
+      - 数据集成:
+         - STAGE: MatrixOne/Develop/data-integration/stage-datalink.md
       - 租户设计:
         - 多租户概述: MatrixOne/Develop/Publish-Subscribe/multi-account-overview.md
         - 发布订阅: MatrixOne/Develop/Publish-Subscribe/pub-sub-overview.md