パッケージ「sqldf」APIドキュメント和訳

# はじめに

RのデータフレームをSQLで扱うことができるパッケージ「sqldf」。
Rを使い始めた頃、簡単なデータ加工をどうやって実現するかいちいち躓いていたときに、このパッケージを使うことで使い慣れたSQLでサクサク書くことができ、頼りきりでした。
Rの関数などをある程度覚えた今でも、少し複雑な加工をする際などに重宝しています。

ここでは、sqldfのAPIドキュメント（Version 0.4-10）の一部を和訳します。

sqldf APIドキュメント
http://cran.r-project.org/web/packages/sqldf/sqldf.pdf

# 和訳

## sqldf-package

*sqldf パッケージ概要*

#### 説明

RのデータフレームでSQLのselectを行う簡単な方法を提供します。

#### 詳細

パッケージはsqldfという単一の関数を持ちます。そのヘルプに、詳細な情報と例があります。

#### 参照

sqldfのヘルプページが、第一のドキュメントです。
sqldfのホームページ http://sqldf.googlecode.com にはSQLiteのページヘのリンクがあり、クエリを考える際に役立ちます。

## read.csv.sql

*ファイルをSQLで絞り込んで読み込む*

#### 説明

ファイルを、SQL文で絞り込んでRに読み込みます。
絞りこまれた部分のみRで処理されるので、通常であればRで扱うには大きすぎるファイルも、扱うことができます。

#### 使い方
```lang:R
read.csv.sql(file, sql = "select * from file", header = TRUE, sep = ",",
row.names, eol, skip, filter, nrows, field.types,
colClasses, dbname = tempfile(), drv = "SQLite", ...)
```

```lang:R
read.csv2.sql(file, sql = "select * from file", header = TRUE, sep = ";",
row.names, eol, skip, filter, nrows, field.types,
colClasses, dbname = tempfile(), drv = "SQLite", ...)
```

#### 引数

**file**

ファイルパスかURL（http:// または ftp:// で始まるもの）。
引数 "filter" が使われ、ファイルをfilterに入力しなくて良い場合、fileは省略または、NULL、NA、""を設定できます。

**sql**

SQL文の文字列。
ファイルを表すテーブルは、"file" で参照できます。

**header**

read.csvと同様。

**sep**

read.csvと同様。

**row.names**

read.csvと同様。

**eol**

行末文字。

**skip**

入力ファイル内の、指定された行数をスキップします。

**filter**

指定された場合、入力ファイルがパイプされるshell/batchのコマンドです。
read.csv2.sqlでは、Windows以外のシステムではtr , .が初期値です。（※ ←ここの訳が怪しいです。）
ファイル内のすべてのカンマをドットに置換します。
Windowsでは、同様の機能が提供されますが、trコマンドをエミュレートするため、sqldfに含まれるvbscriptが使われます。

**nrows**

列の型を決めるために使われる行数。
初期値は50。
-1にした場合、列の型を決めるためにすべての行が使われます。
この引数は、頻繁には使われません。

**field.types**

名前がその列の列名で、値がSQLiteの型（Rのクラス名ではなく）であるリスト。
これらの型を指定することが、処理を速くすることに繋がります。
スピードがそれほど重要でない場合、この引数は通常は使う必要ありません。

**colClasses**

read.csvと同様。

**dbname**

sqldf関数と同様に、初期値はtempfile()です。
NULLを指定した場合、メモリ内のデータベースが使われ、スピードは向上しますが、データベースのサイズは利用可能なメモリサイズにより制限されます。

**drv**

この引数は無視されます。
現在、read.csv.sql、read.csv2.sqlでサポートされているデータベースはSQLiteだけです。
H2データベースはビルトインのSQL関数CSVREADを持っていて、read.csv.sqlの代わりに使えます。

**...**

sqldf関数に譲ります。

#### 詳細

指定したファイルをSQLデータベースに読み込みます。その際、データベースが既に存在しなければ、新しく作成します。
その後、SQL文を適用し、結果をデータフレームとして返します。
該当のSQL文より前にデータベースが存在しなかった場合、データベースを削除します。

この関数はSQLiteを用いてファイルを読み込むため、スピードはあるもののRでの処理ほど融通が効かないことに注意してください。
例えば、この関数はクォーテーションで囲まれた列を特別なものとして認識せず、クォーテーションを列の一部だと認識します。
詳細は、sqldf関数のヘルプをご覧ください。

read.csv2.sqlはread.csv.sqlとほぼ同様ですが、デフォルトのsepが";"であり、デフォルトのfilterがファイル中のすべてのカンマを小数点（つまりドット）に置き換えます。

Windowsでは、filter引数が使われ、レジストリに Rtools が見つかった場合、パスを明記せずこれらのtoolsを使えるように、Rtoolsのbinディレクトリが検索パスに追加されます。

#### 戻り値

SQL文がselect文である場合、データフレームが返されます。

#### 使用例

```lang:R
## Not run:
# might need to specify eol= too depending on your system
write.csv(iris, "iris.csv", quote = FALSE, row.names = FALSE)
iris2 <- read.csv.sql("iris.csv",
sql = "select * from file where Species = 'setosa' ")
## End(Not run)
```

## sqldf

#### 説明
データフレームに対するSQL select

#### 使い方
```lang:R
sqldf(x, stringsAsFactors = FALSE,
row.names = FALSE, envir = parent.frame(),
method = getOption("sqldf.method"),
file.format = list(), dbname, drv = getOption("sqldf.driver"),
user, password = "", host = "localhost", port,
dll = getOption("sqldf.dll"), connection = getOption("sqldf.connection"),
verbose = isTRUE(getOption("sqldf.verbose")))
```

#### 引数

**x**

SQLのselect文の文字列、または、一連のSQL文のベクトル。
select文の構文は、使用する特定のデータベースに従う必要があります。
xを省略した場合、後続のsqldf文がアクセスするためのコネクションを確立します。
その場合、次のx無しのsqldf文までは、データベースは破棄されません。

**stringsAsFactors**

TRUEの場合、データベースから"character"で出力された列は、（heuristicがクラスを特定できない場合）"factor"に変換されます。

**row.names**

TRUEの場合、データベースのテーブルに、対応するデータフレームのrow nameの入った「row_names」列が与えられます。
SQLiteの場合は、いずれの場合でも、特別なrowid（またはoid、_rowid_）が利用可能です。

**envir**

テーブルを表すデータフレームを探す環境（environment）。

**method**

※ ここの訳は若干怪しいです。

この引数は2つの関数、キーワード、文字列のベクトルのリストです。
リストの2つ目の要素がNULLである場合（デフォルト）、1つ目の要素は、リストによりラッピングしなくても指定できます。
1つ目の要素はデータベースから出力データフレームへの変換方法を示し、2つ目は各データフレームがデータベースに読み込まれる際の変換を示します。
2つ目の要素はあまり使われません。

1つ目の要素がNULLまたは指定されなかった場合、初期値は"auto"です。
2つ目の要素がNULLまたは指定されなかった場合、入力に対して変換は行われません。

1つ目の要素に対して許可されたキーワードは、
(1) 後で記述するheuristicを用いて各列のクラスを自動で採用する"auto"（デフォルト）、
(2) "auto" と同じだが "factor" や "ordered" クラスを採用しない "auto.factor"、
(3) 自動処理なしにデータベースから返ってきたクラスをそのまま使うことを表す "raw" またはNULL、
(4) \___classのように、アンダースコア2つとRのクラス（たとえばDate）で終わる列名がそのクラスに変換され、 __classの部分が列名から除去される "name\__class"
です。

例えば、

```lang:R
sqldf("select a as x__Date from DF", method = "name__class")
```

はクラスがDateで列名がxの列となります。

methodの1つ目の要素はまた、返ってくるデータフレームに採用されるクラスの文字列のベクトルとすることもできます。
今示した例は、代わりに以下のようにも実装できます。

```lang:R
sqldf("select a as x from DF", method = "Date")
```
Dateがこのように使われる場合、データベースが1970-01-01からの日数を持っていることを想定していることに注意してください。
日付がyyyy-mm-ddのフォーマットである場合、クラスとしてDate2を用いてください。

**file.format**

※ ここの訳はかなり怪しいです。訳者はsqliteImportFileというものについての知識がゼロです。

その要素がsqliteImportFileに渡されるリスト。
要素はsep、header、row.names、skip、eol、filterを含みます。

filterを除き、それらはsqliteImportFileに渡され、sqliteImportFileのものと同じ初期値を持ちます。
（ただし、eolは、使用するオペレーティングシステムの行末の文字列を初期値とします。読み込まれたファイルが、使用しているプラットフォームの行末文字を持っていない場合、eolを明記してください。特に、WindowsでのUNIXライクなツールは、UNIXの行末文字を持つファイルを作ることがあるので、そのような場合はeol="\n"のように指定すると良いでしょう。）

filterはオプションとしてbatch/shellコマンドを含み、入力ファイルは読み込まれる前に、それによってパイプされます。
filterは、最初の要素がbatch/shellコマンドであるリストであり、後続の要素の名前に相当する名前を持つかもしれません。
これらの後続の各要素は、sqldfが一時ファイルを読み込む文字列のベクトルです。
一時ファイルの名前は、コマンドに置き換えられます。

例えば、

```lang:R
filter = list("gawk -f prog", prog = '{ print gensub(/,/, ".", "g") }')
```
. command line quoting which may vary among shells and Windows. 

上で論じたように、filterがWindows上でのUNIX行末文字を持つファイルを作る場合、eolが設定される必要があります。

file.format may be set to NULL in order not to search for input file objects at all. 
The file.format can also be specified as an attribute in each file object itself in which case such specification overrides any given through the argument list.
There is further discussion of file.format below.

**dbname**

データベース名。
SQLite、h2の各データベースでは、これの初期値は":memory:"で、組込のデータベースが使われます。
MySQLでは初期値は getOption("RMysql.dbname") であり、これが設定されていなければ "test" が使われます。
RPostgreSQLでは初期値は getOption("sqldf.RPostgreSQL.dbname") であり、これが設定されていなければ "test" が使われます。


**drv**

"SQLite"、"MySQL"、"h2"、"PostgreSQL"、"pgSQL"のいずれかか、その頭に"R"をつけたもの。
指定されない場合、"dbDriver"オプションがチェックされます。
それも設定されていない場合、sqldfはRPostgreSQL、RMySQLまたはRH2が読み込まれているかその順番にチェックし、最初に一致したドライバーが使われます。
そのどれも読み込まれていない場合、"SQLite"が使われます。
dbname=NULL とすると、初期値が使用されます。

**user**

ユーザー名。
組込データベースの場合は不要です。
RPostgreSQLでは、初期値は sqldf.RPostgreSQL.user のオプションのものが使われ、それがなければ "postgres" が使われます。

**password**

パスワード。
組込データベースの場合は不要です。
RPostgreSQLでは、初期値は sqldf.RPostgreSQL.password のオプションのものが使われ、それがなければ "postgres" が使われます。

**host**

ホスト。
通常は、デフォルトの"localhost"で十分です。
RPostgreSQLでは、初期値は sqldf.RPostgreSQL.host のオプションのものが使われ、それがなければ "test" が使われます。


続きは徐々に追記します。