http://git-wip-us.apache.org/repos/asf/hbase/blob/7bf6c024/src/main/docbkx/external_apis.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/external_apis.xml b/src/main/docbkx/external_apis.xml deleted file mode 100644 index e4c9f23..0000000 --- a/src/main/docbkx/external_apis.xml +++ /dev/null @@ -1,427 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter version="5.0" xml:id="external_apis" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> -<!-- -/** - * 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. - */ ---> - <title>Apache HBase External APIs</title> - This chapter will cover access to Apache HBase either through non-Java languages, or through custom protocols. - - <section xml:id="nonjava.jvm"> - <title>Non-Java Languages Talking to the JVM</title> - <para>Currently the documentation on this topic in the - <link xlink:href="http://wiki.apache.org/hadoop/Hbase";>Apache HBase Wiki</link>. - See also the <link xlink:href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/thrift/package-summary.html#package_description";>Thrift API Javadoc</link>. - </para> - </section> - - <section xml:id="rest"> - <title>REST</title> - <para>Currently most of the documentation on REST exists in the - <link xlink:href="http://wiki.apache.org/hadoop/Hbase/Stargate";>Apache HBase Wiki on REST</link> (The REST gateway used to be - called 'Stargate'). There are also a nice set of blogs on <link xlink:href="http://blog.cloudera.com/blog/2013/03/how-to-use-the-apache-hbase-rest-interface-part-1/";>How-to: Use the Apache HBase REST Interface</link> - by Jesse Anderson. - </para> - </section> <!-- rest --> - - <section xml:id="thrift"> - <title>Thrift</title> - <para>Currently most of the documentation on Thrift exists in the - <link xlink:href="http://wiki.apache.org/hadoop/Hbase/ThriftApi";>Apache HBase Wiki on Thrift</link>. - </para> - <section xml:id="thrift.filter-language"><title>Filter Language</title> - <section xml:id="use-case"><title>Use Case</title> - <note> - <para>this feature was introduced in Apache HBase 0.92</para> - </note> - <para>This allows the user to perform server-side filtering when accessing HBase over Thrift (or in the shell -- see the 'scan' help in the shell). - The user specifies a filter via a string. The string is parsed on the server to construct the filter</para> - </section> - - <section xml:id="general-syntax"><title>General Filter String Syntax</title> - <para>A simple filter expression is expressed as: <code>âFilterName (argument, argument, ... , argument)â</code></para> - <para>You must specify the name of the filter followed by the argument list in parenthesis. Commas separate the individual arguments</para> - <para>If the argument represents a string, it should be enclosed in single quotes.</para> - <para>If it represents a boolean, an integer or a comparison operator like <, - >, != etc. it should not be enclosed in quotes</para> - <para>The filter name must be one word. All ASCII characters are allowed except for whitespace, single quotes and parenthesis.</para> - <para>The filterâs arguments can contain any ASCII character. <code>If single quotes are present in the argument, they must be escaped by a - preceding single quote</code></para> - </section> - - <section xml:id="compound-filters-and-operators"><title>Compound Filters and Operators</title> - <para>Currently, two binary operators â AND/OR and two unary operators â WHILE/SKIP are supported.</para> - <para>Note: the operators are all in uppercase</para> - <para><emphasis role="bold">AND</emphasis> â as the name suggests, if this - operator is used, the key-value must pass both the filters</para> - <para><emphasis role="bold">OR</emphasis> â as the name suggests, if this operator - is used, the key-value must pass at least one of the filters</para> - <para><emphasis role="bold">SKIP</emphasis> â For a particular row, if any of the - key-values donât pass the filter condition, the entire row is skipped</para> - <para><emphasis role="bold">WHILE</emphasis> - For a particular row, it continues - to emit key-values until a key-value is reached that fails the filter condition</para> - <para><emphasis role="bold">Compound Filters:</emphasis> Using these operators, a - hierarchy of filters can be created. For example: <code>â(Filter1 AND Filter2) OR (Filter3 AND Filter4)â</code></para> - </section> - - <section xml:id="order-of-evaluation"><title>Order of Evaluation</title> - <para>Parenthesis have the highest precedence. The SKIP and WHILE operators are next and have the same precedence.The AND operator has the next highest precedence followed by the OR operator.</para> - <para>For example:</para> - <para>A filter string of the form:<code>âFilter1 AND Filter2 OR Filter3â</code> - will be evaluated as:<code>â(Filter1 AND Filter2) OR Filter3â</code></para> - <para>A filter string of the form:<code>âFilter1 AND SKIP Filter2 OR Filter3â</code> - will be evaluated as:<code>â(Filter1 AND (SKIP Filter2)) OR Filter3â</code></para> - </section> - - <section xml:id="compare-operator"><title>Compare Operator</title> - <para>A compare operator can be any of the following:</para> - <orderedlist> - <listitem> - <para>LESS (<)</para> - </listitem> - <listitem> - <para>LESS_OR_EQUAL (<=)</para> - </listitem> - <listitem> - <para>EQUAL (=)</para> - </listitem> - <listitem> - <para>NOT_EQUAL (!=)</para> - </listitem> - <listitem> - <para>GREATER_OR_EQUAL (>=)</para> - </listitem> - <listitem> - <para>GREATER (>)</para> - </listitem> - <listitem> - <para>NO_OP (no operation)</para> - </listitem> - </orderedlist> - <para>The client should use the symbols (<, <=, =, !=, >, >=) to express - compare operators.</para> - </section> - - <section xml:id="comparator"><title>Comparator</title> - <para>A comparator can be any of the following:</para> - <orderedlist> - <listitem> - <para><emphasis role="bold">BinaryComparator</emphasis> - This - lexicographically compares against the specified byte array using - Bytes.compareTo(byte[], byte[])</para> - </listitem> - <listitem> - <para><emphasis role="bold">BinaryPrefixComparator</emphasis> - This - lexicographically compares against a specified byte array. It only compares up to - the length of this byte array.</para> - </listitem> - <listitem> - <para><emphasis role="bold">RegexStringComparator</emphasis> - This compares - against the specified byte array using the given regular expression. Only EQUAL - and NOT_EQUAL comparisons are valid with this comparator</para> - </listitem> - <listitem> - <para><emphasis role="bold">SubStringComparator</emphasis> - This tests if - the given substring appears in a specified byte array. The comparison is case - insensitive. Only EQUAL and NOT_EQUAL comparisons are valid with this - comparator</para> - </listitem> - </orderedlist> - <para>The general syntax of a comparator is:<code> ComparatorType:ComparatorValue</code></para> - <para>The ComparatorType for the various comparators is as follows:</para> - <orderedlist> - <listitem> - <para><emphasis role="bold">BinaryComparator</emphasis> - binary</para> - </listitem> - <listitem> - <para><emphasis role="bold">BinaryPrefixComparator</emphasis> - binaryprefix</para> - </listitem> - <listitem> - <para><emphasis role="bold">RegexStringComparator</emphasis> - regexstring</para> - </listitem> - <listitem> - <para><emphasis role="bold">SubStringComparator</emphasis> - substring</para> - </listitem> - </orderedlist> - <para>The ComparatorValue can be any value.</para> - <para>Example1:<code> >, 'binary:abc' </code>will match everything that is lexicographically greater than "abc" </para> - <para>Example2:<code> =, 'binaryprefix:abc' </code>will match everything whose first 3 characters are lexicographically equal to "abc"</para> - <para>Example3:<code> !=, 'regexstring:ab*yz' </code>will match everything that doesn't begin with "ab" and ends with "yz"</para> - <para>Example4:<code> =, 'substring:abc123' </code>will match everything that begins with the substring "abc123"</para> - </section> - - <section xml:id="example PHP Client Program"><title>Example PHP Client Program that uses the Filter Language</title> - <programlisting> -<? $_SERVER['PHP_ROOT'] = realpath(dirname(__FILE__).'/..'); - require_once $_SERVER['PHP_ROOT'].'/flib/__flib.php'; - flib_init(FLIB_CONTEXT_SCRIPT); - require_module('storage/hbase'); - $hbase = new HBase('<server_name_running_thrift_server>', <port on which thrift server is running>); - $hbase->open(); - $client = $hbase->getClient(); - $result = $client->scannerOpenWithFilterString('table_name', "(PrefixFilter ('row2') AND (QualifierFilter (>=, 'binary:xyz'))) AND (TimestampsFilter ( 123, 456))"); - $to_print = $client->scannerGetList($result,1); - while ($to_print) { - print_r($to_print); - $to_print = $client->scannerGetList($result,1); - } - $client->scannerClose($result); -?> - </programlisting> - </section> - - <section xml:id="example-filter-strings"><title>Example Filter Strings</title> - <para> - <itemizedlist> - <listitem> - <para><code>âPrefixFilter (âRowâ) AND PageFilter (1) AND FirstKeyOnlyFilter ()â</code> will return all key-value pairs that match the following conditions:</para> - <para>1) The row containing the key-value should have prefix âRowâ </para> - <para>2) The key-value must be located in the first row of the table </para> - <para>3) The key-value pair must be the first key-value in the row </para> - </listitem> - </itemizedlist> - </para> - - <orderedlist> - <para> - <itemizedlist> - <listitem> - <para><code>â(RowFilter (=, âbinary:Row 1â) AND TimeStampsFilter (74689, 89734)) OR - ColumnRangeFilter (âabcâ, true, âxyzâ, false))â</code> will return all key-value pairs that match both the following conditions:</para> - <para>1) The key-value is in a row having row key âRow 1â </para> - <para>2) The key-value must have a timestamp of either 74689 or 89734.</para> - <para>Or it must match the following condition:</para> - <para>1) The key-value pair must be in a column that is lexicographically >= abc and < xyz </para> - </listitem> - </itemizedlist> - </para> - </orderedlist> - - <para> - <itemizedlist> - <listitem> - <para><code>âSKIP ValueFilter (0)â</code> will skip the entire row if any of the values in the row is not 0</para> - </listitem> - </itemizedlist> - </para> - </section> - - <section xml:id="Individual Filter Syntax"><title>Individual Filter Syntax</title> - <orderedlist> - <listitem> - <para><emphasis role="bold"><emphasis role="underline">KeyOnlyFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter doesnât take any - arguments. It returns only the key component of each key-value. </para> - <para><emphasis role="bold">Syntax:</emphasis> KeyOnlyFilter () </para> - <para><emphasis role="bold">Example:</emphasis> "KeyOnlyFilter ()"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">FirstKeyOnlyFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter doesnât take any - arguments. It returns only the first key-value from each row. </para> - <para><emphasis role="bold">Syntax:</emphasis> FirstKeyOnlyFilter () </para> - <para><emphasis role="bold">Example:</emphasis> "FirstKeyOnlyFilter ()" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">PrefixFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes one argument â a prefix of a - row key. It returns only those key-values present in a row that starts with the - specified row prefix</para> - <para><emphasis role="bold">Syntax:</emphasis> PrefixFilter (â<row_prefix>â) </para> - <para><emphasis role="bold">Example:</emphasis> "PrefixFilter (âRowâ)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline"> - ColumnPrefixFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes one argument - â a column prefix. It returns only those key-values present in a column that starts - with the specified column prefix. The column prefix must be of the form: <code>âqualifierâ </code></para> - <para><emphasis role="bold">Syntax:</emphasis>ColumnPrefixFilter(â<column_prefix>â)</para> - <para><emphasis role="bold">Example:</emphasis> "ColumnPrefixFilter(âColâ)"</para> - </listitem> - - <listitem> - <para><emphasis role="underline"><emphasis role="bold">MultipleColumnPrefixFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a list of - column prefixes. It returns key-values that are present in a column that starts with - any of the specified column prefixes. Each of the column prefixes must be of the form: <code>âqualifierâ</code></para> - <para><emphasis role="bold">Syntax:</emphasis>MultipleColumnPrefixFilter(â<column_prefix>â, â<column_prefix>â, â¦, â<column_prefix>â)</para> - <para><emphasis role="bold">Example:</emphasis> "MultipleColumnPrefixFilter(âCol1â, âCol2â)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">ColumnCountGetFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes one argument - â a limit. It returns the first limit number of columns in the table</para> - <para><emphasis role="bold">Syntax:</emphasis> ColumnCountGetFilter (â<limit>â)</para> - <para><emphasis role="bold">Example:</emphasis> "ColumnCountGetFilter (4)"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">PageFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes one argument - â a page size. It returns page size number of rows from the table. </para> - <para><emphasis role="bold">Syntax:</emphasis> PageFilter (â<page_size>â)</para> - <para><emphasis role="bold">Example:</emphasis> "PageFilter (2)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">ColumnPaginationFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes two - arguments â a limit and offset. It returns limit number of columns after offset number - of columns. It does this for all the rows</para> - <para><emphasis role="bold">Syntax:</emphasis> ColumnPaginationFilter(â<limit>â, â<offest>â) </para> - <para><emphasis role="bold">Example:</emphasis> "ColumnPaginationFilter (3, 5)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">InclusiveStopFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes one argument - â a row key on which to stop scanning. It returns all key-values present in rows up to - and including the specified row</para> - <para><emphasis role="bold">Syntax:</emphasis> InclusiveStopFilter(â<stop_row_key>â) </para> - <para><emphasis role="bold">Example:</emphasis> "InclusiveStopFilter ('Row2')" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">TimeStampsFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a list of - timestamps. It returns those key-values whose timestamps matches any of the specified - timestamps</para> - <para> <emphasis role="bold">Syntax:</emphasis> TimeStampsFilter (<timestamp>, <timestamp>, ... ,<timestamp>) </para> - <para> <emphasis role="bold">Example:</emphasis> "TimeStampsFilter (5985489, 48895495, 58489845945)"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">RowFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a compare - operator and a comparator. It compares each row key with the comparator using the - compare operator and if the comparison returns true, it returns all the key-values in - that row</para> - <para><emphasis role="bold">Syntax:</emphasis> RowFilter (<compareOp>, â<row_comparator>â) </para> - <para><emphasis role="bold">Example: </emphasis>"RowFilter (<=, âxyz)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">Family Filter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a compare - operator and a comparator. It compares each qualifier name with the comparator using - the compare operator and if the comparison returns true, it returns all the key-values - in that column</para> - <para><emphasis role="bold">Syntax:</emphasis> QualifierFilter (<compareOp>, â<qualifier_comparator>â) </para> - <para><emphasis role="bold">Example:</emphasis> "QualifierFilter (=, âColumn1â)"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">QualifierFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a compare - operator and a comparator. It compares each qualifier name with the comparator using - the compare operator and if the comparison returns true, it returns all the key-values - in that column</para> - <para><emphasis role="bold">Syntax:</emphasis> QualifierFilter (<compareOp>,â<qualifier_comparator>â) </para> - <para><emphasis role="bold">Example:</emphasis> "QualifierFilter (=,âColumn1â)"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">ValueFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a compare operator and a - comparator. It compares each value with the comparator using the compare operator and - if the comparison returns true, it returns that key-value</para> - <para><emphasis role="bold">Syntax:</emphasis> ValueFilter (<compareOp>,â<value_comparator>â) </para> - <para><emphasis role="bold">Example:</emphasis> "ValueFilter (!=, âValueâ)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">DependentColumnFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes two arguments â a family - and a qualifier. It tries to locate this column in each row and returns all key-values - in that row that have the same timestamp. If the row doesnât contain the specified - column â none of the key-values in that row will be returned.</para> - <para>The filter can also take an optional boolean argument â dropDependentColumn. If set to true, the column we were depending on doesnât get returned.</para> - <para>The filter can also take two more additional optional arguments â a compare operator and a value comparator, which are further checks in addition to the family and qualifier. If the dependent column is found, its value should also pass the value check and then only is its timestamp taken into consideration</para> - <para><emphasis role="bold">Syntax:</emphasis> DependentColumnFilter (â<family>â, â<qualifier>â, <boolean>, <compare operator>, â<value comparatorâ)</para> - <para><emphasis role="bold">Syntax:</emphasis> DependentColumnFilter (â<family>â, â<qualifier>â, <boolean>) </para> - <para><emphasis role="bold">Syntax:</emphasis> DependentColumnFilter (â<family>â, â<qualifier>â) </para> - <para><emphasis role="bold">Example:</emphasis> "DependentColumnFilter (âconfâ, âblacklistâ, false, >=, âzebraâ)" </para> - <para><emphasis role="bold">Example:</emphasis> "DependentColumnFilter (âconfâ, 'blacklist', true)"</para> - <para><emphasis role="bold">Example:</emphasis> "DependentColumnFilter (âconfâ, 'blacklist')"</para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">SingleColumnValueFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes a column family, a - qualifier, a compare operator and a comparator. If the specified column is not found â - all the columns of that row will be emitted. If the column is found and the comparison - with the comparator returns true, all the columns of the row will be emitted. If the - condition fails, the row will not be emitted. </para> - <para>This filter also takes two additional optional boolean arguments â filterIfColumnMissing and setLatestVersionOnly</para> - <para>If the filterIfColumnMissing flag is set to true the columns of the row will not be emitted if the specified column to check is not found in the row. The default value is false.</para> - <para>If the setLatestVersionOnly flag is set to false, it will test previous versions (timestamps) too. The default value is true.</para> - <para>These flags are optional and if you must set neither or both</para> - <para><emphasis role="bold">Syntax:</emphasis> SingleColumnValueFilter(â<family>â, â<qualifier>â, <compare operator>, â<comparator>â, <filterIfColumnMissing_boolean>, <latest_version_boolean>) </para> - <para><emphasis role="bold">Syntax:</emphasis> SingleColumnValueFilter(â<family>â, â<qualifier>, <compare operator>, â<comparator>â) </para> - <para><emphasis role="bold">Example:</emphasis> "SingleColumnValueFilter (âFamilyAâ, âColumn1â, <=, âabcâ, true, false)" </para> - <para><emphasis role="bold">Example:</emphasis> "SingleColumnValueFilter (âFamilyAâ, âColumn1â, <=, âabcâ)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">SingleColumnValueExcludeFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter takes the same arguments and - behaves same as SingleColumnValueFilter â however, if the column is found and the - condition passes, all the columns of the row will be emitted except for the tested - column value. </para> - <para><emphasis role="bold">Syntax:</emphasis> SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>', <latest_version_boolean>, <filterIfColumnMissing_boolean>)</para> - <para><emphasis role="bold">Syntax:</emphasis> SingleColumnValueExcludeFilter('<family>', '<qualifier>', <compare operator>, '<comparator>') </para> - <para><emphasis role="bold">Example:</emphasis> "SingleColumnValueExcludeFilter (âFamilyAâ, âColumn1â, â<=â, âabcâ, âfalseâ, âtrueâ)"</para> - <para><emphasis role="bold">Example:</emphasis> "SingleColumnValueExcludeFilter (âFamilyAâ, âColumn1â, â<=â, âabcâ)" </para> - </listitem> - - <listitem> - <para><emphasis role="bold"><emphasis role="underline">ColumnRangeFilter</emphasis></emphasis></para> - <para><emphasis role="bold">Description:</emphasis> This filter is used for selecting only those - keys with columns that are between minColumn and maxColumn. It also takes two boolean - variables to indicate whether to include the minColumn and maxColumn or not.</para> - <para>If you donât want to set the minColumn or the maxColumn â you can pass in an empty argument.</para> - <para><emphasis role="bold">Syntax:</emphasis> ColumnRangeFilter (â<minColumn>â, <minColumnInclusive_bool>, â<maxColumn>â, <maxColumnInclusive_bool>)</para> - <para><emphasis role="bold">Example:</emphasis> "ColumnRangeFilter (âabcâ, true, âxyzâ, false)"</para> - </listitem> - - </orderedlist> - </section> - - </section> - - </section> <!-- thrift --> - - <section xml:id="c"> - <title>C/C++ Apache HBase Client</title> - <para>FB's Chip Turner wrote a pure C/C++ client. <link xlink:href="https://github.com/facebook/native-cpp-hbase-client";>Check it out</link>. - </para> - </section> - -</chapter>
http://git-wip-us.apache.org/repos/asf/hbase/blob/7bf6c024/src/main/docbkx/getting_started.xml ---------------------------------------------------------------------- diff --git a/src/main/docbkx/getting_started.xml b/src/main/docbkx/getting_started.xml deleted file mode 100644 index e3e471d..0000000 --- a/src/main/docbkx/getting_started.xml +++ /dev/null @@ -1,232 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter version="5.0" xml:id="getting_started" - xmlns="http://docbook.org/ns/docbook"; - xmlns:xlink="http://www.w3.org/1999/xlink"; - xmlns:xi="http://www.w3.org/2001/XInclude"; - xmlns:svg="http://www.w3.org/2000/svg"; - xmlns:m="http://www.w3.org/1998/Math/MathML"; - xmlns:html="http://www.w3.org/1999/xhtml"; - xmlns:db="http://docbook.org/ns/docbook";> -<!-- -/** - * 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. - */ ---> - <title>Getting Started</title> - - <section> - <title>Introduction</title> - - <para><xref linkend="quickstart" /> will get you up and - running on a single-node, standalone instance of HBase. - </para> - </section> - - <section xml:id="quickstart"> - <title>Quick Start</title> - - <para>This guide describes setup of a standalone HBase instance. It will - run against the local filesystem. In later sections we will take you through - how to run HBase on HDFS, a distributed filesystem. This section - leads you through creating a table, inserting - rows via the HBase <command>shell</command>, and then cleaning - up and shutting down your standalone, local filesystem HBase instance. The below exercise - should take no more than ten minutes (not including download time). - </para> - <note xml:id="local.fs.durability"><title>Local Filesystem and Durability</title> - <para>Using HBase with a LocalFileSystem does not currently guarantee durability. - You need to run HBase on HDFS to ensure all writes are preserved. Running - against the local filesystem though will get you off the ground quickly and get you - familiar with how the general system works so lets run with it for now. See - <link xlink:href="https://issues.apache.org/jira/browse/HBASE-3696"/> and its associated issues for more details.</para></note> - <note xml:id="loopback.ip.getting.started"> - <title>Loopback IP</title> - <para>The below advice is for hbase-0.94.0 (and older) versions; we believe this fixed in hbase-0.96.0 and beyond (let us know if we have it wrong) -- there should be no need of modification to - <filename>/etc/hosts</filename>.</para> - <para>HBase expects the loopback IP address to be 127.0.0.1. Ubuntu and some other distributions, - for example, will default to 127.0.1.1 and this will cause problems for you - <footnote><para>See <link xlink:href="http://blog.devving.com/why-does-hbase-care-about-etchosts/";>Why does HBase care about /etc/hosts?</link> for detail.</para></footnote>. - </para> - <para><filename>/etc/hosts</filename> should look something like this: -<programlisting> - 127.0.0.1 localhost - 127.0.0.1 ubuntu.ubuntu-domain ubuntu -</programlisting> - </para> - </note> - - - <section> - <title>Download and unpack the latest stable release.</title> - - <para>Choose a download site from this list of <link - xlink:href="http://www.apache.org/dyn/closer.cgi/hbase/";>Apache Download - Mirrors</link>. Click on the suggested top link. This will take you to a - mirror of <emphasis>HBase Releases</emphasis>. Click on the folder named - <filename>stable</filename> and then download the file that ends in - <filename>.tar.gz</filename> to your local filesystem; e.g. - <filename>hbase-0.94.2.tar.gz</filename>.</para> - - <para>Decompress and untar your download and then change into the - unpacked directory.</para> - - <para><programlisting>$ tar xfz hbase-<?eval ${project.version}?>.tar.gz -$ cd hbase-<?eval ${project.version}?> -</programlisting></para> - - <para>At this point, you are ready to start HBase. But before starting - it, edit <filename>conf/hbase-site.xml</filename>, the file you write - your site-specific configurations into. Set - <varname>hbase.rootdir</varname>, the directory HBase writes data to, - and <varname>hbase.zookeeper.property.dataDir</varname>, the directory - ZooKeeper writes its data too: -<programlisting><?xml version="1.0"?> -<?xml-stylesheet type="text/xsl" href="configuration.xsl"?> -<configuration> - <property> - <name>hbase.rootdir</name> - <value>file:///DIRECTORY/hbase</value> - </property> - <property> - <name>hbase.zookeeper.property.dataDir</name> - <value>/DIRECTORY/zookeeper</value> - </property> -</configuration></programlisting> Replace <varname>DIRECTORY</varname> in the above with the - path to the directory you would have HBase and ZooKeeper write their data. By default, - <varname>hbase.rootdir</varname> is set to <filename>/tmp/hbase-${user.name}</filename> - and similarly so for the default ZooKeeper data location which means you'll lose all - your data whenever your server reboots unless you change it (Most operating systems clear - <filename>/tmp</filename> on restart).</para> - </section> - - <section xml:id="start_hbase"> - <title>Start HBase</title> - - <para>Now start HBase:<programlisting>$ ./bin/start-hbase.sh -starting Master, logging to logs/hbase-user-master-example.org.out</programlisting></para> - - <para>You should now have a running standalone HBase instance. In - standalone mode, HBase runs all daemons in the the one JVM; i.e. both - the HBase and ZooKeeper daemons. HBase logs can be found in the - <filename>logs</filename> subdirectory. Check them out especially if - it seems HBase had trouble starting.</para> - - <note> - <title>Is <application>java</application> installed?</title> - - <para>All of the above presumes a 1.6 version of Oracle - <application>java</application> is installed on your machine and - available on your path (See <xref linkend="java" />); i.e. when you type - <application>java</application>, you see output that describes the - options the java program takes (HBase requires java 6). If this is not - the case, HBase will not start. Install java, edit - <filename>conf/hbase-env.sh</filename>, uncommenting the - <envar>JAVA_HOME</envar> line pointing it to your java install, then, - retry the steps above.</para> - </note> - </section> - - <section xml:id="shell_exercises"> - <title>Shell Exercises</title> - - <para>Connect to your running HBase via the <command>shell</command>.</para> - - <para><programlisting>$ ./bin/hbase shell -HBase Shell; enter 'help<RETURN>' for list of supported commands. -Type "exit<RETURN>" to leave the HBase Shell -Version: 0.90.0, r1001068, Fri Sep 24 13:55:42 PDT 2010 - -hbase(main):001:0> </programlisting></para> - - <para>Type <command>help</command> and then - <command><RETURN></command> to see a listing of shell commands and - options. Browse at least the paragraphs at the end of the help emission - for the gist of how variables and command arguments are entered into the - HBase shell; in particular note how table names, rows, and columns, - etc., must be quoted.</para> - - <para>Create a table named <varname>test</varname> with a single column family named <varname>cf</varname>. - Verify its creation by listing all tables and then insert some - values.</para> - - <para><programlisting>hbase(main):003:0> create 'test', 'cf' -0 row(s) in 1.2200 seconds -hbase(main):003:0> list 'test' -.. -1 row(s) in 0.0550 seconds -hbase(main):004:0> put 'test', 'row1', 'cf:a', 'value1' -0 row(s) in 0.0560 seconds -hbase(main):005:0> put 'test', 'row2', 'cf:b', 'value2' -0 row(s) in 0.0370 seconds -hbase(main):006:0> put 'test', 'row3', 'cf:c', 'value3' -0 row(s) in 0.0450 seconds</programlisting></para> - - <para>Above we inserted 3 values, one at a time. The first insert is at - <varname>row1</varname>, column <varname>cf:a</varname> with a value of - <varname>value1</varname>. Columns in HBase are comprised of a column family prefix -- - <varname>cf</varname> in this example -- followed by a colon and then a - column qualifier suffix (<varname>a</varname> in this case).</para> - - <para>Verify the data insert by running a scan of the table as follows</para> - - <para><programlisting>hbase(main):007:0> scan 'test' -ROW COLUMN+CELL -row1 column=cf:a, timestamp=1288380727188, value=value1 -row2 column=cf:b, timestamp=1288380738440, value=value2 -row3 column=cf:c, timestamp=1288380747365, value=value3 -3 row(s) in 0.0590 seconds</programlisting></para> - - <para>Get a single row</para> - - <para><programlisting>hbase(main):008:0> get 'test', 'row1' -COLUMN CELL -cf:a timestamp=1288380727188, value=value1 -1 row(s) in 0.0400 seconds</programlisting></para> - - <para>Now, disable and drop your table. This will clean up all done - above.</para> - - <para><programlisting>hbase(main):012:0> disable 'test' -0 row(s) in 1.0930 seconds -hbase(main):013:0> drop 'test' -0 row(s) in 0.0770 seconds </programlisting></para> - - <para>Exit the shell by typing exit.</para> - - <para><programlisting>hbase(main):014:0> exit</programlisting></para> - </section> - - <section xml:id="stopping"> - <title>Stopping HBase</title> - - <para>Stop your hbase instance by running the stop script.</para> - - <para><programlisting>$ ./bin/stop-hbase.sh -stopping hbase...............</programlisting></para> - </section> - - <section> - <title>Where to go next</title> - - <para>The above described standalone setup is good for testing and - experiments only. In the next chapter, <xref linkend="configuration" />, - we'll go into depth on the different HBase run modes, system requirements - running HBase, and critical configurations setting up a distributed HBase deploy.</para> - </section> - </section> - -</chapter>
