apop_db.c File Reference

Data Structures

• struct callback_t
• struct tab_exists_t

Defines

• #define Fillin(query, fmt)

Functions

• void apop_db_rng_init (int seed)
• int apop_db_open (char *filename)
• int apop_table_exists (char *name, char remove)
• int apop_db_close (char vacuum)
• int apop_query (const char *fmt,...)
• apop_data * apop_query_to_text (const char *fmt,...)
• apop_data * apop_query_to_data (const char *fmt,...)
• gsl_matrix * apop_query_to_matrix (const char *fmt,...)
• gsl_vector * apop_query_to_vector (const char *fmt,...)
• double apop_query_to_float (const char *fmt,...)
• apop_data * apop_query_to_mixed_data (const char *typelist, const char *fmt,...)
• void qxprintf (char **q, char *format,...)
• void apop_matrix_to_db (const gsl_matrix *data, const char *tabname, const char **headers)
• void apop_data_to_db (const apop_data *set, const char *tabname)
• void apop_db_merge_table (char *db_file, char *tabname, char inout)
• void apop_db_merge (char *db_file, char inout)
• double apop_db_t_test (char *tab1, char *col1, char *tab2, char *col2)
• double apop_db_paired_t_test (char *tab1, char *col1, char *col2)

Variables

• apop_opts_type apop_opts

---

Detailed Description

An easy front end to SQLite. Includes a few nice features like a variance, skew, and kurtosis aggregator for SQL.

---

Define Documentation

#define Fillin	(	query,
		fmt		)

Value:

char      *query;                 \
  va_list   argp;                   \
     va_start(argp, fmt);            \
     vasprintf(&query, fmt, argp);   \
     va_end(argp);                   \
     if (apop_opts.verbose) {printf("\n%s\n",query);}

---

Function Documentation

int apop_db_close

(

char

vacuum

)

Closes the database on disk. If you opened the database with apop_db_open(NULL), then this is basically optional.

Parameters:

vacuum

'v': vacuum---do clean-up to minimize the size of the database on disk. 'q': Don't bother; just close the database. (default = 'q')

This function uses the Designated initializers syntax for inputs.

void apop_db_merge	(	char *	db_file,
		char	inout
	)

Merge a database on the hard drive with the database currently open.

Parameters:

	db_file	The name of a file on disk. [No default; can't be NULL]
	inout	Do we copy data in to the currently-open main db ['i'] or out to the specified auxiliary db['o']? [default = 'i']

If a table exists in the new database but not in the currently open one, then it is simply copied over. If there are tables with the same name in both databases, then the data from the new table is inserted into the main database's table with the same name. [The function just calls insert into main.tab select * from merge_me.tab.]

• This is sqlite-only; I'm not sure if it really makes much sense for mySQL.

This function uses the Designated initializers syntax for inputs.

void apop_db_merge_table	(	char *	db_file,
		char *	tabname,
		char	inout
	)

Merge a single table from a database on the hard drive with the database currently open.

Parameters:

	db_file	The name of a file on disk. [default = NULL]
	tabname	The name of the table in that database to be merged in. [No default]
	inout	Do we copy data in to the currently-open main db ['i'] or out to the specified auxiliary db['o']? [default = 'i']

If the table exists in the new database but not in the currently open one, then it is simply copied over. If there is a table with the same name in the currently open database, then the data from the new table is inserted into the main database's table with the same name. [The function just calls insert into main.tab select * from merge_me.tab.]

This function uses the Designated initializers syntax for inputs.

int apop_db_open

(

char *

filename

)

If you want to use a database on the hard drive instead of memory, then call this once and only once before using any other database utilities.

If you want a disposable database which you won't use after the program ends, don't bother with this function.

The trade-offs between an on-disk database and an in-memory db are as one would expect: memory is faster, but is destroyed when the program exits. SQLite includes a command line utility (sqlite3) which let you ask queries of a database on disk, which may be useful for debugging. There are also some graphical front-ends; just ask your favorite search engine for SQLite GUI.

MySQL users: either set the environment variable APOP_DB_ENGINE=mysql or set apop_opts.db_engine = 'm'.

The Apophenia package assumes you are only using a single SQLite database at a time; if not, the apop_db_merge and apop_db_merge_table functions may help.

When you are done doing your database manipulations, be sure to call apop_db_close if writing to disk.

Parameters:

filename

The name of a file on the hard drive on which to store the database. If NULL, then the database will be kept in memory (in which case, the other database functions will call this function for you and you don't need to bother).

Returns:

0: everything OK
1: database did not open.

void apop_db_rng_init

(

int

seed

)

Random numbers are generated inside the database using a separate RNG. This will initialize it for you, just like apop_rng_alloc, except the RNG it produces is kept for internal use. If you don't call it, then it will be called at first use, with seed zero.

Parameters:

seed

The seed. No need to get funny with it: 0, 1, and 2 will produce wholly different streams.

Returns:

The RNG ready for your use.

int apop_table_exists	(	char *	name,
		char	remove
	)

Check for the existence of a table, and maybe delete it.

Recreating a table which already exists can cause errors, so it is good practice to check for existence first. Also, this is the stylish way to delete a table, since just calling "drop table" will give you an error if the table doesn't exist.

Parameters:

	name	the table name (no default)
	remove	'd' ==>delete table so it can be recreated in main. 'n' ==>no action. return result so program can continue. (default)

Returns:

0 = table does not exist
1 = table was found, and if whattodo==1, has been deleted

This function uses the Designated initializers syntax for inputs.

---

Variable Documentation

apop_opts_type apop_opts

Initial value:

 
          { .verbose=0,                    .output_type = 'f',
            .output_pipe = NULL,           .output_delimiter ="\t", 
            .output_append = 0,            .input_delimiters = "| ,\t", 
            .db_name_column = "row_names", .db_nan = "NaN", 
            .db_engine = '\0',             .db_user = "\0", 
            .db_pass = "\0",               .thread_count = 1,
            .rng_seed = 479901,            .version = 0.22 }

Here are where the options are initially set.