Not sure about how to use WQL

[Brett Neumeier]

Hello Wagneers,

I'm having problems getting a query to work. Here's the situation:

I've got a card-type called Affiliation.
I've got a card-type called Person.

Every Person can have an affiliation, and the structure for Person cards includes a reference to +Affiliation, which is constrained to be of Affiliation type.

What I want to do is, for every card that is of Affilation type, include a list of all the Persons who have that Affiliation.

I am sure this must be possible! But I do not get how to do it. I *think* that I include a card of Search type in the structure of all Affiliation cards, but ... composing a query that does what I want is not at all clear to me, even after reading the WQL syntax page a bunch of times.

Can anyone help?

--
Brett Neumeier (bneu...@gmail.com)

[Ethan McCutchen]

Hi Brett,

To answer your question I started a (long overdue) feature card called "relating cards".  The howto section attempts to explain the solution as follows:

relating two card types

 

Suppose your Wagn site has Person cards and Company cards.  You have a Person named George who works for  a Company named Banana Computers, and you'd like to relate George and Banana Computers in such a way that each shows up on the other card.

 

The typical solution is a pointer-search relationship.  It can look something like this:

• On each Person card there is a pointer card named +employer
• George+employer is edited to point to Banana Computers
• On each Company card there is a search card named +employees
• Banana Computers+employees will find George!

The WQL for Banana Computers+employees will look something like this:

{"type":"Person","right_plus":["employer",{"refer_to":"Banana Computers"}]}

In English, this means "find all the cards whose type is Person that have a +employer card that points to Banana Computers.

 

Of course, you wouldn't want to have to write this WQL over and over again for every single Company card, so the common practice is to make the +employees searches into virtual cards.  To do this, you could go to Banana Computers+employees and then click on advanced and create a structure rule that applies to "all +employees cards on Company cards".  (This will create a card called "Company+employees+*type plus right+*structure").  The WQL for that card will look something like this:

 

{"type":"Person","right_plus":["employer",{"refer_to":"_self"}]}

 

Let me know if that works for you!

- ethan

--
You received this message because you are subscribed to the Google Groups "Wagneers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to wagneers+u...@googlegroups.com.
To post to this group, send email to wagn...@googlegroups.com.
Visit this group at http://groups.google.com/group/wagneers.
For more options, visit https://groups.google.com/groups/opt_out.

--
Ethan McCutchen

One of the Wagneers, Wagn.org

Wagn. How pioneers roll.

s: ethan.mccutchen

t: @intogreater

[Brett Neumeier]

On Fri, Nov 1, 2013 at 1:28 PM, Ethan McCutchen <et...@grasscommons.org> wrote:

Hi Brett,

To answer your question I started a (long overdue) feature card called "relating cards".  The howto section attempts to explain the solution as follows:

Thank you very much! That's exactly what I needed.

[...]

{"type":"Person","right_plus":["employer",{"refer_to":"_self"}]}

That works perfectly! I do not think I understand the zen of WQL enough to figure that out on my own, though. Let me see if I can deconstruct this.

"type": "Person" -- that's straightforward: it finds cards of Person type.

"right_plus": [ "employer", { "refer_to": "_self"} ]

That's *less* straightforward. It looks like the key "right_plus" describes any plus-card where the right part of the card matches the query, and [ "employer", { "refer_to": "_self" } ] is a query that says the other_part should be "employer" and the plus_card should be a reference to _self?

That kind of makes sense. But it's not similar enough to the search paradigms I've used before to seem very natural...

--
Brett Neumeier (bneu...@gmail.com)

[Ethan McCutchen]

It's true that WQL is a bit different from most search paradigms.  The difference flows pretty naturally from the way Wagn structures things. WQL is designed for navigating names, types, and content (with particular emphasis on links and inclusions).  This is pretty different from, say, navigating a relational database table.

WQL is also unlike SQL in that it uses an object notation (which can be expressed in JSON, ruby, or other formats).  The rationale there is that this notation will be much easier to manipulate in various ways, such as via a GUI.  We've wanted for years to create a WQL gui and haven't yet, but WQL itself is very coder friendly, so I hope we'll get to tackle that soon.

You correctly pieced apart the WQL query, but let me add a few bits of context / suggestions of best practices.

(As a reminder, on the docs I suggested that we have a Person named George, a Company named Banana Computers, and a Pointer card named "George+employer" that points to Banana Computers.)

"right_plus": [ "employer", { "refer_to": "_self"} ]

In the context of the present search, "_self" is Banana Computers.  And the response we're hoping for is "George".

Among WQL queries, the most unusual thing about "right_plus" is that it requires an array (with hard brackets: []).

You may have noticed that every time you see a Hash / named list in WQL, it represents a card definition which itself can be used as a self-standing WQL query.  This is actually great for debugging.  You can, for example, try the query {"refer_to":"_self"} on its own to see whether you're getting the response you expect.  It's often very useful to build your searches inside out in this way.

So that explains the hash ({}), but why the array ([])?  Well, the issue is that right_plus requires two card definitions.  In essence, the first defines the field, and the second defines the value.  Remember that there is a Pointer card named "George+employer" that points to Banana Computers. We need our query to define both the simple card "employer" and the plus card "George+employer".

Why aren't there two hashes?  Well, in this case, all we need to define the card employer is its name, and the simple string "employer" works as shorthand for that.  But we could certainly use the long form as well:

"right_plus": [ { "name": "employer" }, { "refer_to": "_self"} ]

This gets us back to the issue of why this is all so unconventional looking.  A few key points:

1. The name "right_plus" flows from compound names, which themselves.  It can be taken to mean "cards where +(def1) = (def2)".
2. The two card definitions are unusual because in most systems, the field itself is hard-coded, not part of the data itself.  If you were to write SQL, it might look something like "select * from persons where employer_id = 1234".  Employer_id is part of the data structure, NOT the data.  In Wagn, "employer" is just another card.  Cards are structured by more cards, so WQL must help you navigate both the cards that are structured and the cards that do the structuring. 

None of this is to say that WQL is a perfect finished product.  My best guess is that the future of WQL will involve both of the following:

1. many more tools for manipulating WQL (including GUIs)
2. additional simplified syntax for navigating common relationships
3. other formats that are more friendly for manual manipulation (here's one proposal that Lewis Hoffman offered a while back)

Hope this helps!

- ethan

--

You received this message because you are subscribed to the Google Groups "Wagneers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to wagneers+u...@googlegroups.com.
To post to this group, send email to wagn...@googlegroups.com.
Visit this group at http://groups.google.com/group/wagneers.
For more options, visit https://groups.google.com/groups/opt_out.

[Brett Neumeier]

On Mon, Nov 4, 2013 at 1:20 PM, Ethan McCutchen <et...@grasscommons.org> wrote:

WQL is also unlike SQL in that it uses an object notation (which can be expressed in JSON, ruby, or other formats).  The rationale there is that this notation will be much easier to manipulate in various ways, such as via a GUI.  We've wanted for years to create a WQL gui and haven't yet, but WQL itself is very coder friendly, so I hope we'll get to tackle that soon.

Yes. It seems like there are a small number of core concepts, so I suspect that once I'm past the getting-started hurdles, it won't be difficult to proceed.

(As something of a side note, the thing I find most appealing about wagn is the conceptual integrity it derives from the "everything is a card" foundation.)

Among WQL queries, the most unusual thing about "right_plus" is that it requires an array (with hard brackets: []).

You may have noticed that every time you see a Hash / named list in WQL, it represents a card definition which itself can be used as a self-standing WQL query.  This is actually great for debugging.  You can, for example, try the query {"refer_to":"_self"} on its own to see whether you're getting the response you expect.  It's often very useful to build your searches inside out in this way.

I did *not* notice that, and that's a really good tip! (Does it say that anywhere on the WQL pages on wagn.org? If it does, I missed it.)

Being able to easily experiment and compose the results of experiments is a key enabler that I was missing.

This gets us back to the issue of why this is all so unconventional looking.  A few key points:

1. The name "right_plus" flows from compound names, which themselves.  It can be taken to mean "cards where +(def1) = (def2)".

missing word(s) around "themselves"?

1. The two card definitions are unusual because in most systems, the field itself is hard-coded, not part of the data itself.  If you were to write SQL, it might look something like "select * from persons where employer_id = 1234".  Employer_id is part of the data structure, NOT the data.  In Wagn, "employer" is just another card.  Cards are structured by more cards, so WQL must help you navigate both the cards that are structured and the cards that do the structuring. 

Sure, and that's not even unusual -- in relational databases, one sometimes finds an EAV structure used for storing custom fields. This all seems very similar.

Thanks again!

--
Brett Neumeier (bneu...@gmail.com)

[Ethan McCutchen]

Hi Brett,

I don't think there was any mention of the "inside-out" trick for building WQL queries bit by bit.  I added that to the "Tips" section of the WQL card.

1. The name "right_plus" flows from compound names, which themselves.  It can be taken to mean "cards where +(def1) = (def2)".

missing word(s) around "themselves"?

Yes!  Not sure what I was going for, but I'm going to guess it was something like "compound names, which themselves can be queried based on both their parts and their wholes".

For what it's worth, I'm actually contemplating a proposal to rename the "right_plus", and "left_plus" relationships.  (We'd either migrate old queries or support the old syntax, but we wouldn't just break existing queries).

Would it be more intuitive if "right_plus" were "field" and "left_plus" were "field_of"?  eg:

"field":["employee",{"refer_to":"Banana Computers"}]

would mean "cards with a +employee field that refers to Banana Computers"  (returns George)

Meanwhile, this:

"field_of":["George",{"refer_to":"Banana Computers"}] 

...would return "employee".

This change would reflect a further step in Wagn's gradual embrace of the notion that left and right name parts aren't entirely symmetrical and are increasingly being used where the right means field.

There is a distinct possibility that "plus" will disappear (in favor of requiring an explicit "or" that is actually reflected in the complexity of the SQL generated).  Lewis mentioned this possibility way back when in that compact wql syntax proposal.

Future versions of Wagns will allow "joints" other than the "plus" sign for compound names, and in fact the plus sign may not be the default. This is another reason to get this terminology out of WQL.

Other possible names for left_plus, right_plus, and plus respectively:

• left_child, right_child, child
• has_left, has_right, has_child
• others?

- ethan

--

You received this message because you are subscribed to the Google Groups "Wagneers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to wagneers+u...@googlegroups.com.
To post to this group, send email to wagn...@googlegroups.com.
Visit this group at http://groups.google.com/group/wagneers.
For more options, visit https://groups.google.com/groups/opt_out.

[Brett Neumeier]

It occurs to me belatedly that I never threw in my $0.02 on this question:

On Wed, Nov 6, 2013 at 1:00 PM, Ethan McCutchen <et...@grasscommons.org> wrote:

For what it's worth, I'm actually contemplating a proposal to rename the "right_plus", and "left_plus" relationships.  (We'd either migrate old queries or support the old syntax, but we wouldn't just break existing queries).

Would it be more intuitive if "right_plus" were "field" and "left_plus" were "field_of"?  eg:

"field":["employee",{"refer_to":"Banana Computers"}]

would mean "cards with a +employee field that refers to Banana Computers"  (returns George)

Meanwhile, this:

"field_of":["George",{"refer_to":"Banana Computers"}] 

...would return "employee".

Yes, I find that a great deal more clear! I strongly support that change (or addition).

--
Brett Neumeier (bneu...@gmail.com)