support for best_index/filter

Manifest.txt

@@ -31,6 +31,7 @@ lib/sqlite3/statement.rb
 lib/sqlite3/translator.rb
 lib/sqlite3/value.rb
 lib/sqlite3/version.rb
+lib/sqlite3/vtable.rb
 setup.rb
 tasks/faq.rake
 tasks/gem.rake

ext/sqlite3/database.c

@@ -297,7 +297,7 @@ static VALUE last_insert_row_id(VALUE self)
  return LL2NUM(sqlite3_last_insert_rowid(ctx->db));
 }
 
-static VALUE sqlite3val2rb(sqlite3_value * val)
+VALUE sqlite3val2rb(sqlite3_value * val)
 {
  switch(sqlite3_value_type(val)) {
  case SQLITE_INTEGER:

ext/sqlite3/database.h

@@ -5,6 +5,7 @@
 
 // used by module.c too
 void set_sqlite3_func_result(sqlite3_context * ctx, VALUE result);
+VALUE sqlite3val2rb(sqlite3_value * val);
 
 struct _sqlite3Ruby {
  sqlite3 *db;

ext/sqlite3/module.c

@@ -75,8 +75,136 @@ static int xConnect(sqlite3* db, void *pAux,
  return xCreate(db, pAux, argc, argv, ppVTab, pzErr);
 }
 
+static VALUE constraint_op_as_symbol(unsigned char op)
+{
+ ID op_id;
+ switch(op) {
+ case SQLITE_INDEX_CONSTRAINT_EQ:
+ op_id = rb_intern("==");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_GT:
+ op_id = rb_intern(">");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_LE:
+ op_id = rb_intern("<=");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_LT:
+ op_id = rb_intern("<");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_GE:
+ op_id = rb_intern(">=");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_MATCH:
+ op_id = rb_intern("match");
+ break;
+#if SQLITE_VERSION_NUMBER>=3010000
+ case SQLITE_INDEX_CONSTRAINT_LIKE:
+ op_id = rb_intern("like");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_GLOB:
+ op_id = rb_intern("glob");
+ break;
+ case SQLITE_INDEX_CONSTRAINT_REGEXP:
+ op_id = rb_intern("regexp");
+ break;
+#endif
+#if SQLITE_VERSION_NUMBER>=3009000
+ case SQLITE_INDEX_SCAN_UNIQUE:
+ op_id = rb_intern("unique");
+ break;
+#endif
+ default:
+ op_id = rb_intern("unsupported");
+ }
+ return ID2SYM(op_id);
+}
+
+static VALUE constraint_to_ruby(const struct sqlite3_index_constraint* c)
+{
+ VALUE cons = rb_ary_new2(2);
+ rb_ary_store(cons, 0, LONG2FIX(c->iColumn));
+ rb_ary_store(cons, 1, constraint_op_as_symbol(c->op));
+ return cons;
+}
+
+static VALUE order_by_to_ruby(const struct sqlite3_index_orderby* c)
+{
+ VALUE order_by = rb_ary_new2(2);
+ rb_ary_store(order_by, 0, LONG2FIX(c->iColumn));
+ rb_ary_store(order_by, 1, LONG2FIX(1-2*c->desc));
+ return order_by;
+}
+
 static int xBestIndex(ruby_sqlite3_vtab *pVTab, sqlite3_index_info* info)
 {
+ int i;
+ VALUE constraint = rb_ary_new();
+ VALUE order_by = rb_ary_new2(info->nOrderBy);
+ VALUE ret, idx_num, estimated_cost, order_by_consumed, omit_all;
+#if SQLITE_VERSION_NUMBER >= 3008002
+ VALUE estimated_rows;
+#endif
+#if SQLITE_VERSION_NUMBER >= 3009000
+ VALUE idx_flags;
+#endif
+#if SQLITE_VERSION_NUMBER >= 3010000
+ VALUE col_used;
+#endif
+
+ // convert constraints to ruby
+ for (i = 0; i < info->nConstraint; ++i) {
+ if (info->aConstraint[i].usable) {
+ rb_ary_push(constraint, constraint_to_ruby(info->aConstraint + i));
+ } else {
+ printf("ignoring %d %d\n", info->aConstraint[i].iColumn, info->aConstraint[i].op);
+ }
+ }
+
+ // convert order_by to ruby
+ for (i = 0; i < info->nOrderBy; ++i) {
+ rb_ary_store(order_by, i, order_by_to_ruby(info->aOrderBy + i));
+ }
+
+
+ ret = rb_funcall( pVTab->vtable, rb_intern("best_index"), 2, constraint, order_by );
+ if (ret != Qnil ) {
+ if (!RB_TYPE_P(ret, T_HASH)) {
+ rb_raise(rb_eTypeError, "best_index: expect returned value to be a Hash");
+ }
+ idx_num = rb_hash_aref(ret, ID2SYM(rb_intern("idxNum")));
+ if (idx_num == Qnil ) { 
+ rb_raise(rb_eKeyError, "best_index: mandatory key 'idxNum' not found");
+ }
+ info->idxNum = FIX2INT(idx_num);
+ estimated_cost = rb_hash_aref(ret, ID2SYM(rb_intern("estimatedCost")));
+ if (estimated_cost != Qnil) { info->estimatedCost = NUM2DBL(estimated_cost); }
+ order_by_consumed = rb_hash_aref(ret, ID2SYM(rb_intern("orderByConsumed")));
+ info->orderByConsumed = RTEST(order_by_consumed);
+#if SQLITE_VERSION_NUMBER >= 3008002
+ estimated_rows = rb_hash_aref(ret, ID2SYM(rb_intern("estimatedRows")));
+ if (estimated_rows != Qnil) { bignum_to_int64(estimated_rows, &info->estimatedRows); }
+#endif
+#if SQLITE_VERSION_NUMBER >= 3009000
+ idx_flags = rb_hash_aref(ret, ID2SYM(rb_intern("idxFlags")));
+ if (idx_flags != Qnil) { info->idxFlags = FIX2INT(idx_flags); }
+#endif
+#if SQLITE_VERSION_NUMBER >= 3010000
+ col_used = rb_hash_aref(ret, ID2SYM(rb_intern("colUsed")));
+ if (col_used != Qnil) { bignum_to_int64(col_used, &info->colUsed); }
+#endif
+
+ // make sure that expression are given to filter
+ omit_all = rb_hash_aref(ret, ID2SYM(rb_intern("omitAllConstraint")));
+ for (i = 0; i < info->nConstraint; ++i) {
+ if (RTEST(omit_all)) {
+ info->aConstraintUsage[i].omit = 1;
+ }
+ if (info->aConstraint[i].usable) {
+ info->aConstraintUsage[i].argvIndex = (i+1);
+ }
+ }
+ }
+
  return SQLITE_OK;
 }
 
@@ -117,6 +245,12 @@ static int xNext(ruby_sqlite3_vtab_cursor* cursor)
 static int xFilter(ruby_sqlite3_vtab_cursor* cursor, int idxNum, const char *idxStr,
  int argc, sqlite3_value **argv)
 {
+ int i;
+ VALUE argv_ruby = rb_ary_new2(argc);
+ for (i = 0; i < argc; ++i) {
+ rb_ary_store(argv_ruby, i, sqlite3val2rb(argv[i]));
+ }
+ rb_funcall( cursor->pVTab->vtable, rb_intern("filter"), 2, LONG2FIX(idxNum), argv_ruby );
  cursor->rowid = 0;
  return xNext(cursor);
 }

lib/sqlite3/vtable.rb

@@ -1,4 +1,4 @@
-module SQLite3Vtable
+module SQLite3_VTables
  # this module contains the vtable classes generated 
  # using SQLite3::vtable method
 end
@@ -20,34 +20,52 @@ def close
  # do nothing by default
  end
 
+ #called to define the best suitable index
+ def best_index(constraint, order_by)
+ # one can return an evaluation of the index as shown below
+ # { idxNum: 1, estimatedCost: 10.0, orderByConsumed: true }
+ # see sqlite documentation for more details
+ end
+
+ # may be called several times between open/close
+ # it initialize/reset cursor
+ def filter(idxNum, args)
+ fail 'VTableInterface#filter not implemented'
+ end
+
  # called to retrieve a new row
  def next
  fail 'VTableInterface#next not implemented'
  end
  end
 
- def self.vtable(db, table_name, table_columns)
- if SQLite3Vtable.const_defined?(table_name, inherit = false)
+ def self.vtable(db, table_name, table_columns, enumerable)
+ Module.new(db, 'SQLite3_VTables')
+ if SQLite3_VTables.const_defined?(table_name, inherit = false)
  raise "'#{table_name}' already declared" 
  end
 
- klass = Class.new(VTableInterface) do
- def initialize(enumerable)
- @enumerable = enumerable
- end
- def create_statement
- "create table #{table_name}(#{table_columns})"
- end
- def next
+ klass = Class.new(VTableInterface)
+ klass.send(:define_method, :filter) do |idxNum, args|
+ @enumerable = enumerable.to_enum
+ end
+ klass.send(:define_method, :create_statement) do
+ "create table #{table_name}(#{table_columns})"
+ end
+ klass.send(:define_method, :next) do
+ begin
  @enumerable.next
+ rescue StopIteration
+ nil
  end
  end
 
  begin
- SQLite3Vtable.const_set(table_name, klass)
+ SQLite3_VTables.const_set(table_name, klass)
  rescue NameError
  raise "'#{table_name}' must be a valid ruby constant name"
  end
- db.execute("create virtual table #{table_name} using SQLite3Vtable")
+ db.execute("create virtual table #{table_name} using SQLite3_VTables")
+ klass
  end
 end

test/test_vtable.rb

@@ -3,7 +3,7 @@
 
 #the ruby module name should be the one given to sqlite when creating the virtual table.
 module RubyModule
- class TestVTable < VTableInterface
+ class TestVTable < SQLite3::VTableInterface
  def initialize
  @str = "A"*1500
  end
@@ -17,6 +17,10 @@ def create_statement
  #required method for vtable
  #called before each statement
  def open
+ end
+
+ # this method initialize/reset cursor
+ def filter(id, args)
  @count = 0
  end
 
@@ -66,6 +70,67 @@ def test_working
  assert( nb_row > 0 )
  end
 
+ def test_vtable
+ SQLite3.vtable(@db, 'TestVTable2', 'a, b, c', [
+ [1, 2, 3],
+ [2, 4, 6],
+ [3, 6, 9]
+ ])
+ nb_row = @db.execute('select count(*) from TestVTable2').each.first[0]
+ assert( nb_row == 3 )
+ sum_a, sum_b, sum_c = *@db.execute('select sum(a), sum(b), sum(c) from TestVTable2').each.first
+ assert( sum_a = 6 )
+ assert( sum_b == 12 )
+ assert( sum_c == 18 )
+ end
+
+ def test_multiple_vtable
+ SQLite3.vtable(@db, 'TestVTable3', 'col1', [['a'], ['b']])
+ SQLite3.vtable(@db, 'TestVTable4', 'col2', [['c'], ['d']])
+ rows = @db.execute('select col1, col2 from TestVTable3, TestVTable4').each.to_a
+ assert( rows.include?(['a', 'c']) )
+ assert( rows.include?(['a', 'd']) )
+ assert( rows.include?(['b', 'c']) )
+ assert( rows.include?(['b', 'd']) )
+ end
+
+ def test_best_filter
+ test = self
+ SQLite3.vtable(@db, 'TestVTable5', 'col1, col2', [['a', 1], ['b', 2]]).tap do |vtable|
+ vtable.send(:define_method, :best_index) do |constraint, order_by|
+ # check constraint
+ test.assert( constraint.include?([0, :<=]) ) # col1 <= 'c'
+ test.assert( constraint.include?([0, :>]) ) # col1 > 'a'
+ test.assert( constraint.include?([1, :<]) ) # col2 < 3
+ @constraint = constraint
+
+ # check order by
+ test.assert( order_by == [
+ [1, 1], # col2
+ [0, -1], # col1 desc
+ ] )
+
+ { idxNum: 45 }
+ end
+ vtable.send(:alias_method, :orig_filter, :filter)
+ vtable.send(:define_method, :filter) do |idxNum, args|
+ # idxNum should be the one returned by best_index
+ test.assert( idxNum == 45 )
+
+ # args should be consistent with the constraint given to best_index
+ test.assert( args.size == @constraint.size )
+ filters = @constraint.zip(args)
+ test.assert( filters.include?([[0, :<=], 'c']) ) # col1 <= 'c'
+ test.assert( filters.include?([[0, :>], 'a']) ) # col1 > 'a'
+ test.assert( filters.include?([[1, :<], 3]) ) # col2 < 3
+
+ orig_filter(idxNum, args)
+ end
+ end
+ rows = @db.execute('select col1 from TestVTable5 where col1 <= \'c\' and col1 > \'a\' and col2 < 3 order by col2, col1 desc').each.to_a
+ assert( rows == [['b']] )
+ end
+
  end if defined?(SQLite3::Module)
 end