Document how to query external content tables (addresses #178)

README.md

@@ -3993,6 +3993,32 @@ For more information, see the SQLite documentation about external content tables
 See also [WWDC Companion](https://github.com/groue/WWDCCompanion), a sample app that uses external content tables to store, display, and let the user search the WWDC 2016 sessions.
 
 
+#### Querying External Content Full-Text Tables
+
+When you need to perform a full-text search, and the external content table contains all the data you need, you can simply query the full-text table.
+
+But if you need to load columns from the regular table, and in the same time perform a full-text search, then you will need to query both tables at the same time.
+
+That is because SQLite will throw an error when you try to perform a full-text search on a regular table:
+
+```swift
+// SQLite error 1: unable to use function MATCH in the requested context
+// SELECT * FROM books WHERE books MATCH '...'
+let books = Book.matching(pattern).fetchAll(db)
+```
+
+The solution is to perform a joined request, using raw SQL:
+
+```swift
+let sql = "SELECT books.* " +
+          "FROM books " +
+          "JOIN books_ft ON " +
+          "books_ft.rowid = books.rowid AND " +
+          "books_ft MATCH ?"
+let books = Book.fetchAll(db, sql, arguments: [pattern])
+```
+
+
 ### Full-Text Records
 
 **You can define [record](#records) types around the full-text virtual tables.**

TODO.md

@@ -2,7 +2,7 @@
 - [ ] Enable extended result codes (https://github.com/groue/GRDB.swift/issues/171)
 - [ ] Request.fetchCount() (see https://github.com/groue/GRDB.swift/issues/176#issuecomment-282783884). This method should be a customization point, not an extension.
 - [ ] Check that https://github.com/groue/GRDB.swift/issues/172#issuecomment-282511719 is true (manual deferred foreign key check)
-- [ ] Document how to query external content tables (https://github.com/groue/GRDB.swift/issues/178)
+- [X] Document how to query external content tables (https://github.com/groue/GRDB.swift/issues/178)
 - [ ] SQLiteLib 3.17.0
 - [ ] fts3tokenize was introduced in SQLite 3.7.17 (iOS 8.2 and OS X 10.10). And GRDB uses it before.
 - [ ] Make GRDB less stringly-typed: For each API that eats column names, check if it couldn't eat both Column and String. If this requires Column to adopt ExpressibleByStringLiteral, check if it does not introduce awful ambiguities