[Developers] More information on '/type/reflect'

[David Flanagan]

Sumit wrote:
> Hi,
> Where can I find more reference on the '/type/reflect' properties i.e. 
> /type/reflect/any_master, /type/reflect/any_reverse and 
> /type/reflect/any_value. I see it being used in discussions and mailing 
> lists but was not able to find any info on these topics in the MQL 
> tutorial or the architecture/data model notes.

As far as I know, no such documentation exists yet.  I'm working on 
updating the MQL tutorial to add it, however.

> Here is a case/problem that I am trying to solve
>  - Given a person's name and related information like country of birth, 
> profession, etc. find its freebase id.
>  - The query should not rely on specific types like /location/country as 
> the place associated with a persons name could be a state or city or 
> county too. Same with profession, employers, etc.
> 
> After poking around into lists and discussions I tried the following 
> query which works, at least I think it is working. However I need to 
> read up more on the '/type/reflect' to be confident.
> 
> {
>   "query" : [
>     {
>       "/type/reflect/any_master" : [
>         {
>           "name" : "new zealand"
>         }
>       ],
>       "id" : [],
>       "name" : "peter jackson",
>       "type" : "/people/person"
>     }
>   ]
> }

Here are my comments on this query:

1) Queries of the id property always return a single value, even when an 
object has more than one possible id.  So you can safely use "id":null

2) When you use a /type/reflect property, you find any property with the 
  value you've specified. If you're interested in the name of the 
property that has been matched, add "link":null to the clause.

3) For the kind of generic search you're attempting here, it may not be 
sufficient to just use /type/reflect/any_master.  That will only find 
outgoing links to other objects. It won't find incoming links, and it 
won't find properties that refer to a value rather than to an object. 
  (So if "new zealand" was a value of /type/text rather than a 
/location/country object, it wouldn't be found.  And suppose that 
/location/country had a "famous_person_born_here" property and that this 
was a master property, with its reverse being 
/people/person/countries_claiming_this_person.  Your query using 
any_master wouldn't find a link like that between Peter Jackson and New 
Zealand because it is not a master property of /people/person.

So here's how you might alter your query


[{
  "/type/reflect/any_master" : [{
      "link":null,
      "name":"new zealand"
   }],
  "/type/reflect/any_reverse" : [{
      "link":null,
      "name":"new zealand",
      "optional":true
   }],
  "/type/reflect/any_value" : [{
      "link":null,
      "value":"new zealand"
   }],
  "id" : null,
  "name" : "peter jackson",
  "type" : "/people/person"
}]

Actually, however, the any_value portion of this query doesn't work: it 
won't let me specify a value for the "value" property, only query it 
with null.  I don't know if this is a bug or a legitimate restriction, 
so you either have to query all values of /type/text and see if any of 
them are country names or drop that clause from your query.

If you really do care about searching reverse properties as well as 
outgoing properties, then the problem with the query above is that 
you've got to put optional:true in both clauses, and you'll get lots of 
results that don't match either clause.  A better way (also not yet 
documented) perhaps to do this is to query the links between objects:

[{
   "type":"/type/link",
   "source": {
     "type":"/people/person",
     "name":"peter jackson",
     "id":null
   },
   "target": {"name":"new zealand"},
   "master_property":null,
   "reverse":null
}]

This says: "Return the id of a person named peter jackson who has an 
outgoing or incoming link to or from something named "new zealand". 
Also return the master property name for the link and tell me whether 
the link was reversed in this case."

Here's a version that looks for links to New Zealand or Screenwriter:

[{
   "type":"/type/link",
   "source": {
     "type":"/people/person",
     "name":"peter jackson",
     "id":null
   },
   "target":{
       "name":null,
       "name|=":["new zealand","screenwriter"]
   },
   "master_property":null,
   "reverse":null
}]

Like the /type/reflect/any_master query you started with, this 
/type/link query does not find links that are to /type/text values 
rather than to objects.  To find those, you'd work with the target_value 
property of the link instead of target.

While we're on the topic of undocumented syntax, here's a query that 
says "Return the id and nationality of people named Peter Jackson but 
exclude any who are nationals of any country other than New Zealand." 
This gets you the person you're looking for, plus about four others who 
don't have the nationality property filled in:

[{
  "nationality":null,
  "but:nationality":{
    "optional":"forbidden",
    "name!=":"New Zealand"
  },
  "id" : null,
  "name" : "peter jackson",
  "type" : "/people/person"
}]

I've written some documentation for optional:forbidden and != but it is 
not published yet.  Stay tuned.

Hope this helps!

	David Flanagan

> 
> Thanks.
> Sumit
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> Developers mailing list
> Developers at freebase.com
> http://lists.freebase.com/mailman/listinfo/developers