On this page:
custom-find-one
custom-find-all
custom-g: find
custom-find-count

7 Quick find procedures

 (require (planet untyped/snooze/quick-find))
Quick find procedures provide convenient shorthands for retrieving persistent structs based on the values of their attributes. The procedures can be defined on a per-entity basis using the constructor macros custom-find-one, custom-find-all, custon-find-count and custom-g:find.
The constructor macros are described below and the quick find procedures themselves at the bottom of the page.

(custom-find-one entity kw-arg ...)
 
kw-arg = #:order (order-clause ...)
Defines a quick find wrapper for find-one. entity is the struct type identifier for an entity (e.g. student) and the order-clauses are as they appear in the syntax query language (see sql).

(custom-find-all entity kw-arg ...)
 
kw-arg = #:order (order-clause ...)
Like custom-find-one but defines a wrapper for find-all.

(custom-g:find entity kw-arg ...)
 
kw-arg = #:order (order-clause ...)
Like custom-find-one but defines a wrapper for g:find.

(custom-find-count entity kw-arg ...)
 
kw-arg = #:order (order-clause ...)
Like custom-find-one but defines a wrapper that finds the count of the matching structures in the database.

The quick-find procedures produced are keyword procedures that accept keywords with the same names as the attributes of the relevant entity. For example, the find-person procedure below:
  (define-persistent-struct person
    ([name        type:string]
     [age         type:integer]
     [programmer? type:boolean]))
  
  (define find-person
    (custom-find-one person #:order ((asc person.name))))
would accept keyword arguments for #:name, #:age and #:programmer?. These attribute arguments can be used in the following ways:
  • Passing a boolean, numeric, string, symbol, time-tai or time-utc literal matches structs with a specific attribute value.

  • Passing a list of literals matches structs with any corresponding attribute value.

  • Passing #f for any non-boolean attribute matches structs with null attributes.

  • Passing void matches any value at all (useful when wrapping quick-find calls in other procedures).

  • Arbitrary expressions may be specified by passing a procedure of type (attribute-alias -> expression).

Quick find procedures also accept #:what, #:order, #:limit and #:offset arguments:
  • the #:what argument accepts an entity, attribute, expression, or list of attributes or expression;

  • the #:order argument accepts a list of order terms;

  • the #:limit and #:offset arguments accept a natural number or #f.

Examples:
  ; SELECT * FROM person WHERE name = 'Dave';
  (find-person #:name "Dave")
  ; SELECT * FROM person WHERE name = 'Dave' AND age = 30;
  (find-person #:name "Dave" #:age 30)
  ; SELECT * FROM person WHERE name IN ('Dave', 'Noel', 'Matt');
  (find-person #:name (list "Dave" "Noel" "Matt"))
  ; SELECT * FROM person WHERE name IS NULL AND "programmer?" = false;
  (find-person #:name #f #:programmer? #f)
  ; SELECT * FROM person;
  (find-person #:name (void))
  ; SELECT * FROM person WHERE name ~ 'D.*';
  (find-person #:name (lambda (attr) (sql:regexp-match attr "D.*")))
  ; SELECT surname FROM person;
  (find-person #:what (sql person.surname))
  ; SELECT * FROM person ORDER BY surname DESC;
  (find-person #:order (list (sql (desc person.surname))))