GemFire XD in 15 Minutes

Need a quick introduction to GemFire XD? Take this 15-minute tour to try out the basic features and functionality.

The GemFire XD tutorials expand on these concepts, and demonstrate additional product features. See QuickStart Tutorials.

  1. If you are using the Pivotal HD Single Node VM distribution, or you have already installed GemFire XD, skip to Step 6.
  2. Download the latest GemFire XD .zip file distribution from the product download page: https://network.pivotal.io/products/gemfirexd. Save the downloaded file in your home directory.
  3. Install GemFire XD by uncompressing the downloaded file. For example:
    $ cd ~
    $ unzip Pivotal_GemFireXD_130_b50226_Linux.zip

    Substitute the exact filename that you downloaded.

    This installs GemFire XD in a new Pivotal_GemFireXD_XXX_bNNNNN_Linux subdirectory in your home directory, where XXX is the version of GemFire XD and NNNNN is the specific GemFire XD build number that you downloaded.
  4. If you have not already done so, download and install Java.
    For a list of Java versions supported with this release of GemFire XD, see Supported Configurations and System Requirements.
  5. Set your PATH environment variable to include the bin subdirectory of the GemFire XD directory. For example:
    $ export PATH=$PATH:$HOME/Pivotal_GemFireXD_XXX_bNNNNN_Linux/bin
  6. Create three new directories in your home directory for the locator and two servers that will make up the GemFire XD distributed system:
    $ mkdir locator1 server1 server2
  7. Start the locator:
    $ gfxd locator start -peer-discovery-address=localhost -dir=locator1 -jmx-manager-start=true -jmx-manager-http-port=7075
    Starting GemFireXD Locator using peer discovery on: localhost[10334]
    Starting network server for GemFireXD Locator at address localhost/127.0.0.1[1527]
    GemFireXD Locator pid: 8787 status: running
    Logs generated in /home/yozie/Pivotal_GemFireXD_XXX_bNNNNN_Linux/quickstart/locator1/gfxdlocator.log

    This command starts a default locator that accepts connections on the localhost address. The default port of 10334 is used for communication with other members of the distributed system. (You can double-check that this port is used by examining the locator1/gfxdlocator.log file.) All new members of the distributed system must specify this locator's address and peer discovery port, localhost[10334], in order to join the system.

    The default port of 1527 is used for client connections to the distributed system.

    Specifying -jmx-manager-start=true starts an embedded JMX Manager within the locator. By starting a JMX Manager, you can monitor and browse the GemFire XD distributed system through the Pulse graphical interface.

  8. Start the Pulse monitoring tool by opening a browser and entering the following URL:
    http://localhost:7075/pulse
    At the Pulse login screen, type in the default username admin and password admin. Keep on checking the Pulse tool for corresponding changes as you perform the activities in this quickstart.
  9. Start both servers:
    $ gfxd server start -locators=localhost[10334] -bind-address=localhost -client-port=1528 -dir=server1
    $ gfxd server start -locators=localhost[10334] -bind-address=localhost -client-port=1529 -dir=server2
    Starting GemFireXD Server using locators for peer discovery: localhost[10334]
    Starting network server for GemFireXD Server at address localhost/127.0.0.1[1528]
    GemFireXD Server pid: 8897 status: running
    Logs generated in /home/yozie/Pivotal_GemFireXD_XXX_bNNNNN_Linux/quickstart/server1/gfxdserver.log
    Starting GemFireXD Server using locators for peer discovery: localhost[10334]
    Starting network server for GemFireXD Server at address localhost/127.0.0.1[1529]
    GemFireXD Server pid: 9003 status: running
    Logs generated in /home/yozie/Pivotal_GemFireXD_XXX_bNNNNN_Linux/quickstart/server2/gfxdserver.log

    Both servers also bind to the localhost address. They must specify unique client ports in order to avoid conflicts with the locator's default client port. As an alternative, they could disable the network server entirely by specifying -run-netserver=false, and all clients would need to connect through the locator.

  10. Before going any further, check to make sure that you're in the GemFire XD quickstart subdirectory. You'll need to run the script files in this directory later in the tutorial, and you must execute those scripts from within the quickstart directory. If you installed GemFire XD from the TAR file:
    $ cd ~/Pivotal_GemFireXD_XXX_bNNNNN_Linux/quickstart
    If you are using the Pivotal HD Single Node VM:
    $ cd /usr/lib/gphd/gfxd/quickstart
  11. Connect to the distributed system as a thin client, and display information about the system members:
    $ gfxd
    gfxd> connect client 'localhost:1527';
  12. Now that you're connected to the system, run a simple query to display information about the GemFire XD system members:
    gfxd> select id, kind, netservers from sys.members;
    ID                            |KIND             |NETSERVERS                   
    ------------------------------------------------------------------------------
    localhost(17355):1374         |locator(normal)  |localhost/127.0.0.1[1527]    
    localhost(17535)<v2>:52946    |datastore(normal)|localhost/127.0.0.1[1529]    
    localhost(17438)<v1>:1230     |datastore(normal)|localhost/127.0.0.1[1528]    
    
    3 rows selected
    By default, GemFire XD servers are started as data stores, so that they can host database schemas. In this cluster, you can connect as a client to any member by specifying localhost with the unique port number of the member (the one specified in the NETSERVERS column). However, connecting to the locator provides basic load balancing by routing the connection request to an available server member.
  13. Create a simple table and insert a few rows:
    gfxd> create table quicktable (id int generated always as identity, item char(25));
    0 rows inserted/updated/deleted
    gfxd> insert into quicktable values (default, 'widget');
    1 row inserted/updated/deleted
    gfxd> insert into quicktable values (default, 'gadget');
    1 row inserted/updated/deleted
    gfxd> select * from quicktable;
    ID         |ITEM                     
    -------------------------------------
    2          |gadget                
    1          |widget                   
    
    2 rows selected
  14. By default, GemFire XD replicates new tables that you create onto data store members. You can validate this using the query:
    gfxd> select tablename, datapolicy from sys.systables where tablename='QUICKTABLE';
    TABLENAME                                                    |DATAPOLICY     
    -----------------------------------------------------------------------------
    QUICKTABLE                                                   |REPLICATE      
    
    1 row selected
  15. Execute two SQL scripts to generate a schema that has both replicated and partitioned tables, and then load the schema with data:
    gfxd> run 'create_colocated_schema.sql';
    gfxd> run 'loadTables.sql';

    You see numerous messages as various SQL commands are executed. The first script creates both replicated and partitioned tables, as you can see using the query:

    gfxd> select tablename, datapolicy from sys.systables where tableschemaname='APP';
    TABLENAME                                                     |DATAPOLICY     
    ------------------------------------------------------------------------------
    FLIGHTS_HISTORY                                               |PARTITION      
    FLIGHTAVAILABILITY                                            |PARTITION      
    FLIGHTS                                                       |PARTITION      
    MAPS                                                          |REPLICATE      
    CITIES                                                        |REPLICATE      
    COUNTRIES                                                     |REPLICATE      
    AIRLINES                                                      |REPLICATE      
    QUICKTABLE                                                    |REPLICATE      
    
    8 rows selected
  16. To observe a benefit of table partitioning, look at a query plan that involves one of the partitioned tables. Use the EXPLAIN command with a query to generate a query execution plan:
    gfxd> explain select * from flights;
    The EXPLAIN command stores the query execution plan for the statement in STATEMENTPLANS system table.
  17. To view the details of the query plan, disconnect as a thin client from the distributed system, and then reconnect as a peer client. A peer client participates as a member of the GemFire XD distributed system and can coordinate queries, but it does not host any actual data. Execute these commands:
    gfxd> disconnect;
    gfxd> connect peer 'host-data=false;locators=localhost[10334]';

    You can see that your peer client connection introduces a new member to the distributed system:

    gfxd> select id, kind, netservers from sys.members;
    ID                            |KIND             |NETSERVERS                   
    ------------------------------------------------------------------------------
    localhost(17355):1374         |locator(normal)  |localhost/127.0.0.1[1527]    
    localhost(17438)<v1>:1230     |datastore(normal)|localhost/127.0.0.1[1528]    
    localhost(17535)<v2>:52946    |datastore(normal)|localhost/127.0.0.1[1529]    
    10.0.1.18(17894)<v3>:22695    |accessor(normal) |                             
    
    4 rows selected

    The term accessor indicates that the member only accesses data, but does not store data for the distributed system.

  18. To view the query execution plan that you generated earlier, query the SYS.STATEMENTPLANS table to view the statement ID (STMT_ID), then use EXPLAIN again with the ID to view the plan:
    gfxd> select stmt_id, stmt_text from sys.statementplans;
    STMT_ID                             |STMT_TEXT                              
    -------------------------------------------------------------------------------
    00000001-ffff-ffff-ffff-00020000004c| select * from flights                   
    
    1 row selected
    gfxd> explain '00000001-ffff-ffff-ffff-00020000004c';
    member   localhost(17438)<v1>:1230 begin_execution  2013-02-27 15:33:30.759 end_execution  2013-02-27 15:33:30.779
    QUERY-RECEIVE  execute_time 19.440818 ms member_node localhost(17535)<v2>:52946
      RESULT-SEND  execute_time 0.130708 ms member_node localhost(17535)<v2>:52946
        RESULT-HOLDER  execute_time 10.600616 ms returned_rows 275 no_opens 1
          TABLESCAN (100.00%) execute_time 3.250588 ms returned_rows 275 no_opens 1 scan_qualifiers None scanned_object APP.FLIGHTS scan_type HEAP
    member   localhost(17535)<v2>:52946 begin_execution  2013-02-27 15:33:30.758 end_execution  2013-02-27 15:33:30.89
    QUERY-SCATTER  execute_time 13.358717 ms member_node localhost(17438)<v1>:1230,localhost(17535)<v2>:52946
      QUERY-SEND  execute_time 3.345079 ms member_node localhost(17438)<v1>:1230
        QUERY-SEND  execute_time 1.140207 ms member_node localhost(17535)<v2>:52946
          RESULT-RECEIVE  execute_time 0.008155 ms member_node localhost(17535)<v2>:52946
            RESULT-RECEIVE  execute_time 1.4887 ms member_node localhost(17438)<v1>:1230
              SEQUENTIAL-ITERATION (35.23%) execute_time 10.463731 ms returned_rows 542 no_opens 1
                RESULT-HOLDER  execute_time 0.490328 ms returned_rows 267 no_opens 1 member_node localhost(17535)<v2>:52946
                  RESULT-HOLDER  execute_time 1.65846 ms returned_rows 275 no_opens 1 member_node localhost(17438)<v1>:1230
                    DISTRIBUTION-END (64.76%) execute_time 19.233818 ms returned_rows 542
    Local plan:
    member   localhost(17535)<v2>:52946 begin_execution  2013-02-27 15:33:30.762 end_execution  2013-02-27 15:33:30.842
    TABLESCAN (100.00%) execute_time 3.297607 ms returned_rows 267 no_opens 1 scan_qualifiers None scanned_object APP.FLIGHTS scan_type HEAP
    Note: The generated statement ID may be different on your system. Copy the exact ID from the output of the SELECT statement and paste it into the second EXPLAIN statement.

    The plan describes exactly how GemFire XD performed the query. Note the two QUERY-SEND entries. These entries indicate that the results for the query were obtained from each of the two data store members in the distributed system. Because the FLIGHTS table was created as a partitioned table, new rows that are added to the table are uniquely assigned to partitions based on the partitioning key (in this case, the key is the FLIGHT_ID column). Partitions are then placed on data stores, which can process their portion of the data independently when queries are performed against the table. Results from multiple data stores are then merged on a single query coordinator member to provide the final result set.

  19. Either continue executing queries against the sample database, or shut down the GemFire XD distributed system. To shut down all members of the system, first use the shut-down-all command to stop data stores and accessors. Then shut down any remaining locators:
    gfxd> quit;
    $ gfxd shut-down-all -locators=localhost[10334]
    Connecting to distributed system: locators=localhost[10334]
    Successfully shut down 2 members
    $ gfxd locator stop -dir=locator1
    The GemFireXD Locator has stopped.
  20. To continue learning about GemFire XD, read or work through the remaining QuickStart Tutorials.