docs/_docs/quick-start/getting-started-guide.adoc

// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Getting Started With Ignite 3

This guide shows you how to start working with Ignite 3 using the Ignite CLI.

//NOTE: This is called standalone mode.

== Prerequisites

Ignite 3 was tested on:

include::includes/prereqs.adoc[]

== Install Ignite

To start working with Ignite, you need to install it as described in the link:installation/installing-using-zip[Installation] section.

NOTE: The Unzip operation creates two side-by-side directories: `ignite-db-3.0.0-beta2` and `ignite-cli-3.0.0-beta2`.

== Start Ignite Node

When starting to work with Ignite, first we need to start a Ignite node that will be handling the API calls.

. Navigate to the `ignite-db-3.0.0-beta2` directory.
. Run the `start` command:
+
[tabs]
--
tab:Linux[]
[source, shell]
----
bin/ignite3db start
----

tab:Windows[]
NOTE: You need to install Java in the Bash environment to run Ignite on Windows.
[source, bash]
----
bash bin\ignite3db start
----
--
+
Successful start produces the following output:
+
----
Starting Ignite 3...
Node named defaultNode started successfully. REST addresses are [http://127.0.0.1:10300]”
----

== Optional: Start Multiple Ignite Nodes in Docker

Ignite 3 is designed to work in a cluster of 3 or more nodes at once. While a single node can be used in some scenarios and can be used for the tutorial, having multiple nodes in a cluster is the most common use case.

To run multiple instances of Ignite, you would normally install it on multiple machines before starting a cluster. If you want to emulate a Ignite cluster for this tutorial, use the docker-compose file provided to start them instead.

== Optional: Set Custom JVM Options

You can set custom JVM options when starting the Ignite node by using the `IGNITE3_EXTRA_JVM_ARGS` parameter in the `${IGNITE_HOME}/etc/vars.env` file.

You add the options to the `IGNITE3_EXTRA_JVM_ARGS` parameter using the `-XX` notation. For example:

`IGNITE3_EXTRA_JVM_ARGS  = -XX:+PrintFlagsFinal`

For additional information, see link:https://opensource.com/article/22/4/jvm-parameters-java-developers[this article].

== Activate the Ignite CLI

You initialize your cluster, and perform operations on that cluster, using the link:ignite-cli-tool[Ignite CLI].

To activate the Ignite CLI:

. Navigate to the `ignite-cli-3.0.0-2` directory.
. Run the following command:
+
[tabs]
--
tab:Linux[]
[source, shell]
----
bin/ignite3
----

tab:Windows[]
NOTE: You need to install Java in the Bash environment to run Ignite on Windows.
[source, bash]
----
bash bin\ignite3
----
--

== Initialize Your Cluster

To initialize the cluster that includes the nodes you have started:

. Run the following command:
+ 
----
cluster init -n=sampleCluster -m=defaultNode
----

== Run SQL Statements Against the Cluster

Once your cluster has been initialized, you can manage it with SQL commands:

. Use the `CREATE TABLE` statement to create a new table:
+
----
sql "CREATE TABLE IF NOT EXISTS Person (id int primary key,  city varchar,  name varchar,  age int,  company varchar)"
----
+
. Fill the table with data using the `INSERT` statement:
+
----
sql "INSERT INTO Person (id, city, name, age, company) VALUES ('1', 'London', 'John Doe', '42', 'Apache')"
sql "INSERT INTO Person (id, city, name, age, company) VALUES ('2', 'New York', 'Jane Doe', '36', 'Apache')"
----
+
. Get all data you inserted in the previous step:
+
----
sql "SELECT * FROM Person"
----

NOTE: For more information about available SQL statements, see the link:sql-reference/ddl[SQL Reference] section.

== Manage Cluster Configuration

You can change your cluster or node configuration by using the Ignite CLI.

. To see the current configuration, run the following command:
+
----
node config show --url http://localhost:10300
----
+  
This command prints the configuration file in the HOCON format. Note the `maxSize` value under `aimen.regions`.
+
. Request an increase of the `maxSize` value:
+
----
node config update --url http://localhost:10300 {aimem.regions:[{name:btree_volatile_region,maxSize:412000000}]}
----
+
. To verify the result, run the `show` command again:
+
----
node config show --url http://localhost:10300
----
+
Note that `maxSize` has increased to the value you had requested. 

== Stop the Cluster

After you are done working with your cluster, you need to stop it:

. Navigate to the `ignite-db-3.0.0-beta2` folder.
. Run the `stop` command:

[tabs]
--
tab:Linux[]
----
bin/ignite3db stop
----

tab:Windows[]
----
bash bin\ignite3db stop
----
--

== Next Steps

From here, you may want to:

* Check out the link:ignite-cli-tool[Ignite CLI Tool] page for more detail on supported commands
* Try out our link:https://github.com/apache/ignite-3/tree/main/examples[examples]