Filtering

From The Socknet

Some requests may include a field with a "filter" object, which has a format designed to mimic SQL where clauses.

Contents 1 Filter Format 2 Match Types 2.1 has_exact 3 Examples 4 Considerations

Filter Format

A filter object is a tree structure with an unspecified depth and the following rules:

• The top-level container is an object.
• If the object contains the field and or or, it must contain no other fields.
  • An and or or field must contain an array of two or more filter objects.
• If the object contains fields match_type and match, it must contain both of these fields and no other fields.
  • The field match_type contains a string indicating how matching is to be done.
  • The field match contains data appropriate to the match_type field. See the next section.

Match Types

Depending on the match type in a filter, the match data has certain rules that affect the results.

has_exact

• The data in match must be an object.
• The fields of the object must be present in all results.
• Other fields may also be present.
• If the value for a field is not an object, it must match exactly for all results.
• If the value for a field is an object, these rules are applied recursively.

Examples

These examples apply to the find-messages function.

This example should return any messages that were created by the user http://david.example.com.

{ match_type: "has_exact",
  match: {
           guid: { openid: "http://david.example.com/" }
         }
}

This example should return any messages that were created by either http://david.example.com or http://dan.example.com.

{ or: [
        { match_type: "has_exact",
          match: {
                   guid: { openid: "http://david.example.com/" }
                 }
        }
        { match_type: "has_exact",
          match: {
                   guid: { openid: "http://dan.example.com/" }
                 }
        }
      ]
}

Considerations

The not field is under consideration. Please weigh on the talk page.

Remember, JSON is case-sensitive, so all of these fields are too.

This format was designed to be simple to use to create SQL. A little tweaking will need to be done for each data type. For example, if you use a SQL database table to store your messages, and the field for the user's OpenID is "creator_openid", then your code will need to be able to map guid.openid to "creator_openid".

A really good Socknet library will be able to parse from SQL to this format.