From 2fb3bc70188675af3c2a2995b505779f1dd0bee7 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Thu, 22 Feb 2024 23:07:33 +0100 Subject: [PATCH] Reshaping: Rework "Getting Started" section - Compress the previous pages "introduction", "create-user", and "connect" into a single page "getting-started". - Divert ORM and dataframe content into dedicated pages within the "Integrations" section. - Divert "create-user" page into "Administration" section. --- docs/admin/create-user.md | 62 ++++++++++++++++ docs/admin/index.rst | 1 + docs/domain/timeseries/generate/index.rst | 9 ++- docs/getting-started.md | 79 ++++++++++++++++++++ docs/getting-started/connect.md | 47 ------------ docs/getting-started/create-user.rst | 70 ------------------ docs/getting-started/index.rst | 17 ----- docs/getting-started/introduction.rst | 88 ----------------------- docs/index.md | 3 +- docs/integrate/df.md | 27 +++++++ docs/integrate/index.md | 2 + docs/integrate/orm.md | 14 ++++ 12 files changed, 191 insertions(+), 228 deletions(-) create mode 100644 docs/admin/create-user.md create mode 100644 docs/getting-started.md delete mode 100644 docs/getting-started/connect.md delete mode 100644 docs/getting-started/create-user.rst delete mode 100644 docs/getting-started/index.rst delete mode 100644 docs/getting-started/introduction.rst create mode 100644 docs/integrate/df.md create mode 100644 docs/integrate/orm.md diff --git a/docs/admin/create-user.md b/docs/admin/create-user.md new file mode 100644 index 00000000..d6ca6859 --- /dev/null +++ b/docs/admin/create-user.md @@ -0,0 +1,62 @@ +(create-user)= +# Create User + +This part of the documentation sheds some light on the topics of +[](inv:crate-reference#administration_user_management) and +[](inv:crate-reference#administration-privileges). + + +## Superuser Account + +CrateDB ships with a superuser account called "`crate`", which has the +privileges to perform any action. + +However, with the default configuration, this superuser can only access +CrateDB from the local machine CrateDB has been installed on. If you are +trying to connect from another machine, you are prompted to enter a +username and password. + + +## `CREATE USER` command + +In order to create a user that can be used to authenticate from a remote +machine, first +[install crash](inv:crate-crash:*:label#getting-started) or other +[](inv:crate-clients-tools:*:label#index) on the same machine you installed +CrateDB on. Then, connect to CrateDB running on `localhost`. + +While you can also perform the steps outlined below within +[](inv:crate-admin-ui:*:label#index) itself, the +walkthrough will outline how to do it using the +[](inv:crate-crash:*:label#index) on the command line. + +Invoke Crash within the terminal of your choice. + +```console +sh$ crash +``` + +Add your first user with a secure password to the database: + +```sql +cr> CREATE USER username WITH (password = 'a_secret_password'); +``` + +Grant all privileges to the newly created user: + +```sql +cr> GRANT ALL PRIVILEGES TO username; +``` + +![image](/_assets/img/getting-started/create-user.png){width=640px} + +Now try navigating to the [](inv:crate-admin-ui:*:label#index) in your +browser. In the URL below, please replace `cratedb.example.org` with +the host name or IP address of the machine CrateDB is running on, and +sign in with your newly created user account. + + http://cratedb.example.org:4200/ + +After creating the user and granting all privileges, you should be able +to continue with [the guided tour](#use), connecting to CrateDB from a +remote machine. diff --git a/docs/admin/index.rst b/docs/admin/index.rst index eb894698..31ebf1c1 100644 --- a/docs/admin/index.rst +++ b/docs/admin/index.rst @@ -12,6 +12,7 @@ administration practices. :maxdepth: 1 bootstrap-checks + create-user going-into-production troubleshooting/index diff --git a/docs/domain/timeseries/generate/index.rst b/docs/domain/timeseries/generate/index.rst index 28f609a8..97cd4f08 100644 --- a/docs/domain/timeseries/generate/index.rst +++ b/docs/domain/timeseries/generate/index.rst @@ -4,15 +4,14 @@ Generate time series data ========================= +To work with time series data, you are going to need a source of time series +data. Fortunately, there are many ways to generate time series data, for +example by sampling system metrics on your workstation or server. + CrateDB is purpose-built for working with massive amounts of time series data, like the type of data produced by smart sensors and other `Internet of Things`_ (IoT) devices. -If you want to get a feel for using CrateDB to work with time series data, you -are going to need a source of time series data. Fortunately, there are many -ways to generate time series data by sampling the systems running on your local -computer. - This collection of tutorials will show you how to generate mock time series data about the `International Space Station`_ (ISS) and write it to CrateDB using the client of your choice. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..2fb97ff5 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,79 @@ +(use)= +(getting-started)= + +# Getting Started + + +{#introduction} +## Introduction + +Once CrateDB is [installed and running](#install), you can start to interact +with the database for the first time. + + +{#use-admin-ui} +### The Admin UI + +CrateDB ships with a browser-based administration interface called +[Admin UI](inv:crate-admin-ui:*:label#index). +It is enabled on each CrateDB node, you can use it to inspect and +interact with the whole CrateDB cluster in a number of ways. + +If CrateDB is running on your workstation, access the Admin UI using +`http://localhost:4200/`. Otherwise, replace `localhost` with the +hostname CrateDB is running on. + +When using CrateDB Cloud, the URL will look like +`https://testdrive.aks1.westeurope.azure.cratedb.net:4200/`. + +![image](https://cratedb.com/docs/crate/admin-ui/en/latest/_images/console-query.png){width=320px} +![image](/_assets/img/getting-started/first-use/admin-ui.png){width=320px} + +:::{note} +If you are running CrateDB on a remote machine, you will have to create +a dedicated user account for accessing the Admin UI. See [](#create-user). +::: + + +{#use-crash} +### The CrateDB Shell + +The CrateDB Shell, called `crash`, is an interactive command-line interface +(CLI) program for working with CrateDB on your favorite terminal. To learn more +about it, please refer to its documentation at [](inv:crate-crash:*:label#index). + +![image](https://cratedb.com/docs/crate/crash/en/latest/_images/query.png){width=320px} + + +(connect)= +{#use-dive-in} +{#use-start-building} +## Connect + +You have a variety of options to connect to CrateDB, and integrate it with +off-the-shelve, 3rd-party, open-source, and proprietary applications, mostly +using [CrateDB's PostgreSQL interface]. + +To learn more, please refer to the documentation sections about supported +client drivers, libraries, and frameworks, and corresponding tutorials. + +- [Drivers and Integrations] +- [Database Driver Code Examples] +- [Integration Tutorials] +- [More integration tutorials] + + +:::{tip} +To learn more about all the details of CrateDB features, operations, and +its SQL dialect, please also visit the [CrateDB Reference Manual]. +::: + + + +[CrateDB Cloud]: inv:cloud:*:label#index +[CrateDB Reference Manual]: inv:crate-reference:*:label#index +[CrateDB's PostgreSQL interface]: inv:crate-reference:*:label#interface-postgresql +[Database Driver Code Examples]: inv:crate-clients-tools:*:label#connect +[Drivers and Integrations]: inv:crate-clients-tools:*:label#index +[Integration Tutorials]: #integrate +[More integration tutorials]: https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015 diff --git a/docs/getting-started/connect.md b/docs/getting-started/connect.md deleted file mode 100644 index 000cb294..00000000 --- a/docs/getting-started/connect.md +++ /dev/null @@ -1,47 +0,0 @@ -(connect)= - -# Connect - -You have a variety of options to connect your custom applications to CrateDB, -and to integrate it with 3rd-party applications, mostly using [CrateDB's -PostgreSQL interface]. - -This documentation section lists client drivers, libraries, and frameworks, -which can be used together with CrateDB, and outlines how to use them optimally. - -- [Drivers and Integrations] -- [Integration Tutorials] - -About specific topics, there are code examples for database drivers, -dataframe-, and ORM-libraries. - -- [Database Driver Code Examples] -- SQLAlchemy - - [SQLAlchemy Support], [SQLAlchemy by Example], [SQLAlchemy Code Examples] -- pandas and Dask - - [Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy] - - [Guide to efficient data ingestion to CrateDB with pandas] - - [Guide to efficient data ingestion to CrateDB with pandas and Dask] - - [Efficient batch/bulk INSERT operations with pandas, Dask, and SQLAlchemy] - - [pandas code examples] - - [Dask code examples] -- Polars - - [Polars code examples] - - - - -[CrateDB's PostgreSQL interface]: inv:crate-reference:*:label#interface-postgresql -[Dask code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/dask -[Database Driver Code Examples]: inv:crate-clients-tools:*:label#connect -[Drivers and Integrations]: inv:crate-clients-tools:*:label#index -[Efficient batch/bulk INSERT operations with pandas, Dask, and SQLAlchemy]: https://cratedb.com/docs/python/en/latest/by-example/sqlalchemy/dataframe.html -[Guide to efficient data ingestion to CrateDB with pandas]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas/1541 -[Guide to efficient data ingestion to CrateDB with pandas and Dask]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas-and-dask/1482 -[Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy]: https://community.crate.io/t/importing-parquet-files-into-cratedb-using-apache-arrow-and-sqlalchemy/1161 -[Integration Tutorials]: https://community.crate.io/t/overview-of-cratedb-integration-tutorials/1015 -[pandas code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/pandas -[Polars code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/polars -[SQLAlchemy by Example]: https://cratedb.com/docs/python/en/latest/by-example/index.html#sqlalchemy-by-example -[SQLAlchemy Code Examples]: https://github.com/crate/cratedb-examples/tree/main/by-language/python-sqlalchemy -[SQLAlchemy Support]: https://cratedb.com/docs/python/en/latest/sqlalchemy.html diff --git a/docs/getting-started/create-user.rst b/docs/getting-started/create-user.rst deleted file mode 100644 index cf8ca9d1..00000000 --- a/docs/getting-started/create-user.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _create-user: - -=========== -Create user -=========== - - ------------- -Introduction ------------- - -This part of the documentation sheds some light on the topics of -:ref:`crate-reference:administration_user_management` and -:ref:`crate-reference:administration-privileges`. - -CrateDB ships with a superuser account called "``crate``", which has the -privileges to perform any action. However, with the default configuration, this -superuser can only access CrateDB from the local machine CrateDB has been -installed on. If you are trying to connect from another machine, you are -prompted to enter a username and password. - -In order to create a user that can be used to authenticate from a remote -machine, first :ref:`install crash ` or other -:ref:`crate-clients-tools:index` on the same machine you installed CrateDB on. -Then, connect to CrateDB running on ``localhost``. - -While you can also perform the steps outlined below within -:ref:`crate-admin-ui:index` itself, the walkthrough will outline how to do it -using the :ref:`crate-crash:index` on the command line. - - -------- -Details -------- - -Invoke Crash within the terminal of your choice. - -.. code-block:: console - - sh$ crash - -Add your first user with a secure password to the database: - -.. code-block:: psql - - cr> CREATE USER username WITH (password = 'a_secret_password'); - -Grant all privileges to the newly created user: - -.. code-block:: psql - - cr> GRANT ALL PRIVILEGES TO username; - -.. image:: /_assets/img/getting-started/create-user.png - -Now try navigating to the :ref:`crate-admin-ui:index` in your browser. In the URL -below, please replace ``cratedb.example.org`` with the host name or IP address -of the machine CrateDB is running on and sign in with your newly created user -account:: - - http://cratedb.example.org:4200/ - -You should see something like this: - -.. image:: /_assets/img/getting-started/first-use/admin-ui.png - - -After creating the user and granting all privileges, you should be able to -continue with :ref:`the guided tour ` connecting to CrateDB from a remote -machine. diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst deleted file mode 100644 index dea1b127..00000000 --- a/docs/getting-started/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _use: -.. _getting-started: - -############### -Getting Started -############### - -A collection of CrateDB best practices and tips for common scenarios. - -.. rubric:: Table of contents - -.. toctree:: - :maxdepth: 1 - - introduction - create-user - connect diff --git a/docs/getting-started/introduction.rst b/docs/getting-started/introduction.rst deleted file mode 100644 index 4541cb1b..00000000 --- a/docs/getting-started/introduction.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. _introduction: - -========= -First use -========= - -Once CrateDB is :ref:`installed and running `, you can start to -interact with the database for the first time. - -.. rubric:: Table of contents - -.. contents:: - :local: - - -.. _use-admin-ui: - -Introducing the Admin UI -======================== - -CrateDB ships with a browser-based administration interface called -:ref:`Admin UI `. - -The CrateDB Admin UI runs on every CrateDB node, and you can use it to inspect -and interact with the whole CrateDB cluster in a number of ways. - -We will use the Admin UI throughout this section. - -Access the Admin UI in your browser using a URL like this:: - - http://localhost:4200/ - -If CrateDB is not running locally, replace ``localhost`` with the hostname -CrateDB is running on. - -You should see something like this: - -.. image:: /_assets/img/getting-started/first-use/admin-ui.png - - -.. _use-crash: - -Introducing the CrateDB Shell -============================= - -The CrateDB Shell (aka Crash) is an interactive command-line interface (CLI) -program for working with CrateDB on your favorite terminal. For further -information about it, please follow up on its documentation at -:ref:`crate-crash:index`. - -.. NOTE:: - - If you are running CrateDB on a remote machine, you will have to create a - dedicated user account for accessing the Admin UI. See :ref:`create-user`. - - -.. _use-more-tutorials: - -Follow more tutorials to get a sense of CrateDB -=============================================== - -If you want to get a feel for using CrateDB to work with time series data, you -are going to need a source of time series data. Fortunately, there are many -ways to generate time series data by sampling the systems running on your local -computer. - -The :ref:`next collection of tutorials ` shows how to generate mock -time series data about the International Space Station (ISS) and write it to -CrateDB using the client of your choice. - - -.. _use-start-building: - -Start building with CrateDB clients and tools -============================================= - -If you'd like to skip the tutorials and start building with CrateDB, you can -find a list of :ref:`crate-clients-tools:index` in a different section of the -documentation. - - -.. _use-dive-in: - -Dive into CrateDB -================= - -Check out the :ref:`crate-howtos:index` for goal oriented topics. Alternatively, -check out the :ref:`crate-reference:index` for a complete reference manual. diff --git a/docs/index.md b/docs/index.md index e54bfccf..37190e83 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,7 @@ (guides)= (howtos)= (tutorials)= +(use-more-tutorials)= # The CrateDB Guide @@ -229,7 +230,7 @@ frameworks. :hidden: install/index -getting-started/index +getting-started admin/index reference-architectures/index diff --git a/docs/integrate/df.md b/docs/integrate/df.md new file mode 100644 index 00000000..608998b0 --- /dev/null +++ b/docs/integrate/df.md @@ -0,0 +1,27 @@ +(df)= +(dataframes)= +# Dataframe Libraries + +How to use CrateDB together with popular open-source dataframe libraries. + +## Dask +- [Guide to efficient data ingestion to CrateDB with pandas and Dask] +- [Efficient batch/bulk INSERT operations with pandas, Dask, and SQLAlchemy] +- [Dask code examples] + +## pandas +- [Guide to efficient data ingestion to CrateDB with pandas] +- [Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy] +- [pandas code examples] + +## Polars +- [Polars code examples] + + +[Dask code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/dask +[Efficient batch/bulk INSERT operations with pandas, Dask, and SQLAlchemy]: https://cratedb.com/docs/python/en/latest/by-example/sqlalchemy/dataframe.html +[Guide to efficient data ingestion to CrateDB with pandas]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas/1541 +[Guide to efficient data ingestion to CrateDB with pandas and Dask]: https://community.crate.io/t/guide-to-efficient-data-ingestion-to-cratedb-with-pandas-and-dask/1482 +[Importing Parquet files into CrateDB using Apache Arrow and SQLAlchemy]: https://community.crate.io/t/importing-parquet-files-into-cratedb-using-apache-arrow-and-sqlalchemy/1161 +[pandas code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/pandas +[Polars code examples]: https://github.com/crate/cratedb-examples/tree/main/by-dataframe/polars diff --git a/docs/integrate/index.md b/docs/integrate/index.md index 7a27ad94..9bf9bc5f 100644 --- a/docs/integrate/index.md +++ b/docs/integrate/index.md @@ -13,6 +13,8 @@ optimally. ```{toctree} :maxdepth: 2 +orm +df etl/index metrics/index visualize/index diff --git a/docs/integrate/orm.md b/docs/integrate/orm.md new file mode 100644 index 00000000..73181332 --- /dev/null +++ b/docs/integrate/orm.md @@ -0,0 +1,14 @@ +(orm)= +# ORM Libraries + +How to use CrateDB together with popular open-source ORM libraries. + +## SQLAlchemy +- [The CrateDB SQLAlchemy Dialect] +- [Working with SQLAlchemy and CrateDB] +- [SQLAlchemy Code Examples] + + +[SQLAlchemy Code Examples]: https://github.com/crate/cratedb-examples/tree/main/by-language/python-sqlalchemy +[The CrateDB SQLAlchemy Dialect]: https://cratedb.com/docs/python/en/latest/sqlalchemy.html +[Working with SQLAlchemy and CrateDB]: https://cratedb.com/docs/python/en/latest/by-example/index.html#sqlalchemy-by-example