![\"C](\"https:\/\/griddb.net\/wp-content\/uploads\/2017\/09\/dreamstime_xs_55515590.jpg\")
GridDB’s C client API has support for CentOS 6.7<\/strong> and CentOS 7.3<\/strong>. The client is compatible gcc version-4.8.5<\/strong> and can be used with either Community or Standard edition. The C client’s Standard Edition version supports all the functionality as its Java counterpart with support for Geometry columns and operations etc. The files and instructions to setup the C client for Community Edition can all be found on the GridDB Github page<\/a> If for some reason, either the configure<\/code> or bootstrap.sh<\/code> scripts throw errors, install the following libraries with these commands.<\/p>\n$ sudo yum groupinstall ‘Development Tools'\n$ sudo yum makecache fast\n<\/pre>\nWhen running the<\/p>\n
make<\/code> command, if the error **recursive error<\/em> is thrown, a quick fix is to ensure the above libraries are installed. Then remove the c_client<\/em> directory by obtaining and cloning a new one from Github C repository<\/a>. From there you can test the client by running a few sample programs provided in the c_client repository to test the client and your GridDB connection. Some things to note about compiling and linking C client files with GridDB. When compiling with gcc<\/code>, the include (-I)<\/code> flag should point to an include<\/code> directory with the gridstore.h<\/code> file. The library, or (-L)<\/code> flag should always point to the bin<\/em> directory in the c-client folder that has .so<\/code> file and symbolic links.<\/p>\n$ ls c_client\/bin\nlibgridstore.so\nlibgridstore.so.0\nlibgridstore.so.0.0.0\n<\/pre>\nYou should use the<\/p>\n
-lgridstore<\/code> option as well to successfully compile the file. Also for your compiled executables to successfully run, the environment variable known as LD_LIBRARY_PATH<\/code> needs to be set. This variable needs to point to the bin<\/code> folder in the GridDB C-client directory. Example compilation of a C source code file.<\/p>\n$ export LD_LIBRARY_PATH=\/path\/to\/c_client\/bin\n$ gcc -o cSample cSample.c -I.\/include -L.\/bin -lgridstore\n$ .\/cSample 239.0.0.1 31999 defaultCluster admin admin\n<\/pre>\nA more detailed for the C API reference can be found<\/p>\n
here<\/a>.<\/p>\nPython\/Ruby API Setup {#python-intro} GridDB gives support for Python 2.6, 2.7, and now Python 3.6. One important thing to successfully build the Python library you will need to have the C client successfully built. You will also need the development kits for Python and Ruby installed as well.<\/h3>\n$ sudo yum install ruby-devel\n$ sudo yum install python-devel\n<\/pre>\nYou will also need the SWIG and pcre libraries as well. Installation instructions and sample programs can be found at the<\/p>\n
griddb_client<\/a> page as well. An important thing to know about using the Python or Ruby library is that the C client has to be installed and setup because variables in the client’s Makefile<\/code> point to the c_client library. If you have the C client setup then your environment variable LD_LIBRARY_PATH<\/code> should be set. You will need this variable’s value to successfully build the client library files for both Ruby and Python. Simply edit this line in the Makefile<\/strong>.<\/p>\nLDFLAGS = -L\/path\/c_client\/library\/bin -lpthread -lrt -lgridstore\n<\/pre>\nIn the Makefile, the default version of Python used is Python 2.6. If you want to use 2.7 or Python 3.6 simply edit line 11 of the<\/p>\n
Makefile<\/code> so the make<\/code> command can successfully run. Example of changing Makefile Python version from 2.6 to 2.7: Line 11 of Makefile<\/code>:<\/p>\nINCLUDES_PYTHON = $(INCLUDES) -I\/usr\/include\/python2.6 ## Before Makefile used (Python 2.6)\n## Change it to\nINCLUDES_PYTHON = $(INCLUDES) -I\/usr\/include\/python2.7 ## After, now uses (Python 2.7)\n<\/pre>\nIn your source code, simply import the<\/p>\n
griddb_python_client<\/code> file so you have access to the gridstore functions. A reference for Python’s API can be found here<\/a>.<\/p>\nRuby API Features {#ruby-intro} When cloning the repository for the GridDB Python client, you will also get all the files needed to build and run the Ruby client as well. GridDB supports Ruby version 1.8 and version 2.4. Details on how to build and run the Ruby client can be found in the<\/h3>\n
ReadME.md<\/code> of the griddb_client page<\/a>. Similar rules apply to the Ruby client as the Python client. The one difference is that in your source code simply require<\/code> the ‘griddb_ruby_client'<\/code> which refers to the griddb_ruby_client.so<\/code> file that contains the Ruby client library. A reference for Ruby’s API can be found here<\/a>.<\/p>\nConnecting to your GridDB Cluster {#connect-intro} For the most part connecting to a GridDB cluster in the C\/Python\/Ruby APIs are similar to connecting to GridDB in the Java API. Create a<\/h2>\n
Properties<\/strong> object or similar data structure and fill in the fields with the host, port, and configuration settings of the database you wish to connect to. Then simply use a StoreFactory<\/code> object to fetch a connection with those properties to retrieve a Gridstore<\/code> instance which will represent the connection to GridDB.<\/p>\nC<\/h4>\n#include \"gridstore.h\"\n\/\/ (snip)\nGSGridStore* gridstore;\nconst GSPropertyEntry properties[] = {\n {\"notificationAddress\",host},\n {\"notificationPort\",port},\n {\"clusterName\",clusterName},\n {\"user\",username},\n {\"password\",password}\n};\nsize_t propertyCount = sizeof(properties) \/ sizeof(*properties);\ngsGetGridStore(gsGetDefaultFactory(),properties,propertyCount,&gridstore);\n<\/pre>\nPython<\/h4>\n#!\/usr\/bin\/python\nimport sys\nimport griddb_python_client\n# (snip)\ngriddb = griddb_python_client\nfactory = griddb.StoreFactory.get_default()\ntry:\n gridstore = factory.get_store({\n \"notificationAddress\":host,\n \"notificationPort\": port,\n \"clusterName\":cluster,\n \"user\":user,\n \"password\":password\n })\n<\/pre>\nRuby<\/h4>\n#!\/usr\/bin\/ruby\n$:.unshift File.dirname(__FILE__)\nrequire 'griddb_ruby_client'\nGriddb = Griddb_ruby_client\nfactory = Griddb::StoreFactory.get_default()\ngridstore = factory.get_store({\n \"notificationAddress\"=> ARGV[0],\n \"notificationPort\"=> ARGV[1],\n \"clusterName\"=> ARGV[2],\n \"user\"=> ARGV[3],\n \"password\"=> ARGV[4]\n }) \n<\/pre>\nIssuing TQL Queries {#tql-intro} In GridDB’s C API there are a variety of built-in functions for querying and aggregating rows in a container. For the most part though the simplest and easiest way to make and issue a query to a container is to use a TQL string.<\/h2>\n
TQL<\/strong> is GridDB’s simplified form of SQL querying. The query begins as a TQL string. From there a query<\/em> object is formed by issuing that TQL to a container which can then be fetched to retrieve a resulting set of rows. The resulting row set<\/em> can then be iterated over to get individual row and column values. Aggregation results<\/em> are also retrieved from row sets. This flow is fairly the same for the C, Python, and Ruby APIs.<\/p>\nTQL Query in C {#tql-c} Like many other querying languages, you can perform<\/h3>\n
string operations<\/a> like length checking, substring slicing, and pattern recognition with GridDB’s TQL.<\/p>\nDevice nextDevice;\nGSQuery* generalQuery;\nGSRowSet* generalRowSet;\n\ngsQuery(collection, \n\"select * where (SUBSTRING(name,8,3)='r12' OR name LIKE '%LUE%R55_') and CHAR_LENGTH(name) > 4\", &generalQuery);\n\ngsFetch(generalQuery,GS_FALSE,&generalRowSet);\nprintf(\"Performing a String Operation on Collection ampCollection151 in TQLnn\");\nwhile(gsHasNextRow(generalRowSet)){\n GSChar timeString[GS_TIME_STRING_SIZE_MAX];\n gsGetNextRow(generalRowSet,&nextDevice); \/\/ Obtain row object\n gsFormatTime(nextDevice.timestamp,timeString,sizeof(timeString)); \/\/ Format timestamp number\n\n printf(\"Row in collection ampMeter151: Name=%s\",nextDevice.name);\n printf(\" Amperage = %.2lf\",nextDevice.amperage);\n printf(\" Count = %d\",nextDevice.count);\n printf(\" Timestamp = %sn\",timeString);\n<\/pre>\nOutput<\/strong><\/p>\nPerforming a String Operation on Collection ampCollection151 in TQL\n\nRow in collection ampMeter151: Name=ampMeter12 Amperage = 1.45 \nCount = 3 Timestamp = 2017-09-15T18:13:52.710Z\nRow in collection ampMeter151: Name=BLUESEAMETER555 Amperage = 2.43 \nCount = 5 Timestamp = 2017-09-15T18:13:52.710Z\n<\/pre>\nPython {#tql-python} With the exception of Geometry-specific queries and functions, TQL can be used to make any query in both the Python and Ruby API. For example, while there are no built-in functions to perform Timeseries aggregations in Python, they can be issued in TQL. These include time-specific queries and functions in GridDB like time-sampling, time-averages, and interpolation.<\/h3>\n
TQL Time Query in Python<\/strong><\/p>\nquery = timeseries.query(select * where timestamp > TIMESTAMPADD(HOUR,NOW(),-12)”)\nrowSet = query.fetch(False)\nwhile rowSet.has_next():\n rowSet.get_next(row)\n time = row.get_field_as_timestamp(0)\n voltage = row.get_field_as_double(2)\n print(Voltage at timestamp: {0} is {1} volts in Timeseries voltmeter2.”.format(time,voltage)\n<\/pre>\nOutput<\/strong><\/p>\nVoltage at timestamp: 1505398224644 is 12.34 volts in Timeseries voltmeter2\n<\/pre>\nRuby {#tql-ruby} You can also combine certain aggregation functions with time-specific functions in TQL as well.<\/h3>\n
Aggregation TQL Query in Ruby<\/strong><\/p>\nupdate = false\ntimestamp = Griddb::Timestamp.current()\naggCommand = \"select AVG(voltage) from voltmeter502 where timestamp > TIMESTAMPADD(MINUTE, \nTO_TIMESTAMP_MS(#{timestamp}), -10) AND timestamp < TIMESTAMPADD(MINUTE, \nTO_TIMESTAMP_MS(#{timestamp}), 10)\"\naggQuery = timeseries.query(aggCommand) \naggRowSet = aggQuery.fetch(update)\nwhile aggRowSet.has_next()\n aggResult = aggRowSet.get_next_aggregation()\n print \"Aggregation Result from voltmeter502: Average voltage = #{aggResult.get_double()}n\"\nend\n<\/pre>\nOutput<\/strong><\/p>\nAggregation result from voltmeter502: Average voltage = 10.5\n<\/pre>\nInserting Collection into GridDB with C API {#insert-collection-c} In C, schemas for containers can be created and updated into GridDB using either static schemas or dynamic schemas. Static schemas come in the form of struct bindings. Dynamic schemas come in the form of<\/h3>\n
columnInfo<\/code> and containerInfo<\/code> objects that can be used to update or insert containers.
\nCreating a Static Schema with a C-Struct<\/strong><\/p>\ntypedef struct {\n const GSChar* name;\n double amperage;\n int count;\n GSTimestamp timestamp;\n} Device; \/\/ Static Column Schema in GridDB C API\n<\/pre>\nTo use the struct as a schema for a container in GridDB, you need to create a<\/p>\n
struct-binding<\/em> for it where you define what is the row-key and explicitly assign a type to each of the fields in the struct.
\nCreating a Column Schema from a Struct<\/strong><\/p>\nGS_STRUCT_BINDING(Device,\n GS_STRUCT_BINDING_KEY(name,GS_TYPE_STRING)\n GS_STRUCT_BINDING_ELEMENT(amperage,GS_TYPE_DOUBLE)\n GS_STRUCT_BINDING_ELEMENT(count,GS_TYPE_INTEGER)\n GS_STRUCT_BINDING_ELEMENT(timestamp,GS_TYPE_TIMESTAMP));\n<\/pre>\nFrom there once the struct has been bound and made into a row schema it can be used in containers.<\/p>\n
Inserting a Struct Binding Schema into a Container<\/strong><\/p>\nGSCollection* collection;\ngsPutCollection(gridstore,\"ampCollection151\",GS_GET_STRUCT_BINDING(Device),NULL,GS_FALSE,&collection);\n<\/pre>\nFrom there the<\/p>\n
Device<\/code> struct can be used as a row<\/em> object to fetch and insert rows.
\nInserting a Struct as a GSRow<\/strong><\/p>\nDevice insertionDevice;\ninsertionDevice.name = \"ampMeter12\";\ninsertionDevice.amperage = 1.45;\ninsertionDevice.count = 3;\ninsertionDevice.timestamp = gsCurrentTime();\n<\/pre>\nHaving a Struct Represent a Row Schema<\/strong><\/p>\nDevice device;\nwhile(gsHasNextRow(rowSet)){\n gsGetNextRow(rowSet,&device);\n GSChar timeStr[GS_TIME_STRING_SIZE_MAX];\n gsFormatTime(device.timestamp,timeStr,sizeof(timeStr));\n printf(\"Device in ampCollection151: \");\n printf(\"name=%s\",device.name);\n printf(\" amperage=%.2lf\",device.amperage);\n printf(\" count=%d\",device.count);\n printf(\" timestamp=%sn\",timeStr);\n<\/pre>\nOutput<\/strong><\/p>\nDevice in ampCollection151: name=ampMeter12 amperage=1.45 count=3 \ntimestamp=2017-09-14T20:05:06.285Z\n<\/pre>\nPython {#timeseries-insert-python} In both Python and Ruby, the approach to creating schemas and inserting containers is similar to the dynamic approach shown with the C API. Simply give your columns and container a name and define their column types. Determine whether they are TimeSeries or Collections and what indexes they should have. The column types available can be found in the<\/h3>\n
GridDB documentation<\/a> and API references<\/a>.
\nInserting a Timeseries in Python<\/strong><\/p>\ntimeseries = gridstore.put_container(\"voltmeter2\",[\n (\"timestamp\",griddb.GS_TYPE_TIMESTAMP),\n (\"active\",griddb.GS_TYPE_BOOL),\n (\"voltage\",griddb.GS_TYPE_DOUBLE)\n ],griddb.GS_CONTAINER_TIME_SERIES)\n<\/pre>\nIn Python since there is no need to explicitly state the types of variables. Row fields can be inserted and fetched a lot more fluidly. All that needs to be known is the column type and index. The created row object will have its row schema set by the container it is based off of. Inserting a row can be done as below.<\/p>\n
Inserting a Row in Python<\/strong><\/p>\n## Create rows and set all Row Fields\ninsertionRow = timeseries.create_row()\ninsertionRow.set_field_by_timestamp(0,griddb.Timestamp_add_time(griddb.Timestamp_current(),-6, \n griddb.GS_TIME_UNIT_HOUR))\n\ninsertionRow.set_field_by_bool(1,True)\ninsertionRow.set_field_by_double(2, 12.34)\n\n## Insert Row into Timeseries\ntimeseries.put_row(insertionRow)\n<\/pre>\nRuby {#insert-collection-ruby} The same process is used to create schemas and containers in Ruby as<\/h3>\n