Documentation for CONTAINS() in FQL?

Question

There have recently been several questions posted on Facebook.SO using CONTAINS() in the WHERE clause. It seems to work like the Graph API search function, AND functions as an indexed field. All great things for the FQL developer.

SELECT name,
       username,
       type
FROM   profile
WHERE  CONTAINS("Facebook")

However, the only official mention of the CONTAINS function appears in the unified_thread documentation. It is mentioned in passing, as a way to search for text contained in a message. It also appeared in this fbrell code sample.

But Contains doesn't seem to be a straightforward search. For example, this query:

SELECT name
FROM   user
WHERE  CONTAINS("Joe Biden")

returns "Joe Biden" and also "Joseph Biden" and "Biden Joe". But it also returns "Joe Scardino", "Lindsay Noyan" and "Mehmad Moha" among others. What relationship do these people have with the VP of the USA? They aren't my friends, so I'll never know.

There also appears to be the ability to pass CONTAINS a field to search on, however changing the end of my first query to `CONTAINS("Facebook", name) returns an OAuth error:

 (#615) 'name' is not a valid search field for the profile table.

In my not-so rigorous testing, I have yet to find a field/table combination that does not return this error.

So what is this mystery function? How does it work? Can it allow us to do things to date impossible in FQL like traversing arrays and filtering data stored in strings?

An answer here would be great, but a description on an FQL functions & methods reference page on the official developer documentation site would be better still.

Answer 1

I don't think that a have any great answers here, but I can give a workaround for the issue of returning unrelated names- which I suspect is because people have made public posts about Joe Biden, liked him, or so on. If you do the following:

SELECT name
FROM   user
WHERE  CONTAINS("Joe Biden")
AND    strpos(lower(name),lower("Joe Biden")) >=0

You will get a resultset that only contains the right names- though it removes the advantage of also returning Joseph Biden, etc. etc.

My personal point of pain is that CONTAINS() appears to work with partial strings (e.g. "Joe Bide") on the profile table, but not on the user table. Very frustrating.