Queries

Functions

• 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,...)

---

Detailed Description

These functions query the database, and most return a value for use on the C-side.

In all cases, your query may be in printf form. For example:

char tabname[] = "demographics";
char colname[] = "heights";
int min_height = 175;
apop_query("select %s from %s where %s > %i", colname, tabname, colname, min_height);

• Blanks in the database (i.e., NULLs) and elements that match apop_opts.db_nan are filled with NANs in the matrix.

---

Function Documentation

int apop_query	(	const char *	fmt,
			...
	)

Send a query to the database, return nothing

Parameters:

fmt

A printf-style SQL query.

apop_data* apop_query_to_data	(	const char *	fmt,
			...
	)

Queries the database, and dumps the result into an apop_data set.

If apop_opts.db_name_column is set (it defaults to being "row_names"), and the name of a column matches the name, then the row names are read from that column.

double apop_query_to_float	(	const char *	fmt,
			...
	)

Queries the database, and dumps the result into a single double-precision floating point number.

Returns:

A double, actually. This calls apop_query_to_matrix and returns the (0,0)th element of the returned matrix. Thus, if your query returns multiple lines, you will get no warning, and the function will return the first in the list (which is not always well-defined).

If the query returns no rows at all, the function returns NAN.

gsl_matrix* apop_query_to_matrix	(	const char *	fmt,
			...
	)

Queries the database, and dumps the result into a matrix.

apop_data* apop_query_to_mixed_data	(	const char *	typelist,
		const char *	fmt,
			...
	)

Query data to an apop_data set, but a mix of names, vectors, matrix elements, and text.

If you are querying to a matrix and maybe a name, use apop_query_to_data (and set apop_opts.db_name_column if desired). But if your data is a mix of text and numbers, use this.

The first argument is a character string consisting of the letters nvmtw, one for each column of the SQL output, indicating whether the column is a name, vector, matrix colum, text column, or weight vector. You can have only one n, v, and w.

If the query produces more columns than there are elements in the column specification, then the remainder are dumped into the text section. If there are fewer columns produced than given in the spec, the additional elements will be allocated but not filled (i.e., they are uninitialized and will have garbage).

The 'n' character indicates row, meaning that apop_opts.db_name_column is ignored).

As with the other apop_query_to_... functions, the query can include printf-style format specifiers.

apop_data* apop_query_to_text	(	const char *	fmt,
			...
	)

Dump the results of a query into an array of strings.

Returns:

An apop_data structure with the text element filled. Notice that this is always a 2-D array, even if the query returns a single column. In that case, use returned_tab->text[i][0] to refer to row i.

For example, the following function will list the tables in a database (much like you could do from the command line using sqlite3 dbname.db ".table").

#include <apop.h>

void print_table_list(char *db_file){
apop_data   *tab_list;
int         i;
        apop_db_open(db_file);
        tab_list= apop_query_to_text("select name from sqlite_master where type==\"table\";");
        for(i=0; i< tab_list->textsize[0]; i++)
                printf("%s\n", tab_list->text[i][0]);
}

int main(int argc, char **argv){
    if (argc == 1){
        printf("Give me a database name, and I will print out the list of tables contained therein.\n");
        return 0; 
    }
    print_table_list(argv[1]);
}

gsl_vector* apop_query_to_vector	(	const char *	fmt,
			...
	)

Queries the database, and dumps the first column of the result into a gsl_vector.

Returns:

A gsl_vector holding the first column of the returned matrix. Thus, if your query returns multiple lines, you will get no warning, and the function will return the first in the list.

If the query returns no columns at all, the function returns NULL.