z_search (zotonic_core v1.0.0-rc.17)

Search the database, interfaces to specific search routines.

Summary

Types

search_offset/0
search_options/0
search_query/0

Functions

concat_sql_query(Search_sql, Limit1)
default_pagelen(Context)
lookup_qarg(Arg, Terms)

Find a named argument in a query terms list or map.

lookup_qarg(Arg, Terms, Default)
lookup_qarg_value(Arg, Terms)

Find the term value of a named argument in a query terms list or map.

lookup_qarg_value(Arg, Terms, Default)

Find the term value of a named argument in a query terms list or map. Return the default when the term is not found or doesn't have a value.

map_to_options(Map)

Map a map with (binary) search options to a search option list.

props_to_map(Props)

Change a search props list to a standard query format.

query_(Args, Context)

Given a query as proplist or map, return all results.

reformat_sql_query(Search_sql, Options, Context)

Inject the ACL checks in the SQL query.

search(Search, Context) deprecated

Search with the question and return the results

search(Search, MaxRows, Context) deprecated

Perform the named search and its arguments

search(Name, Args, Page, PageLen, Context)

Perform a named search with arguments.

search(Name, Args, Page, PageLen, Options, Context)

Perform a named search with arguments.

search_pager(Query, Page, Context) deprecated

Search items and handle the paging. Uses the default page length.

search_pager(Query, Page, PageLen, Context)

Search items and handle the paging. This fetches extra rows beyond the requested rows to ensure that the pager has the information for the "next page" options. The number of extra rows depends on the current page, more for page 1, less for later pages.

search_result(Result, Limit, Context)

Handle a return value from a search function. This can be an intermediate SQL statement that still needs to be augmented with extra ACL checks.

Types

search_offset/0

-type search_offset() :: Limit :: pos_integer() | {Offset :: pos_integer(), Limit :: pos_integer()}.

search_options/0

-type search_options() ::
          #{properties => [binary()] | boolean(),
            is_count_rows => boolean(),
            is_single_page => boolean()}.

search_query/0

-type search_query() :: {atom(), list()} | {binary(), map() | undefined}.

Functions

concat_sql_query(Search_sql, Limit1)

default_pagelen(Context)

-spec default_pagelen(z:context()) -> pos_integer().

lookup_qarg(Arg, Terms)

-spec lookup_qarg(Arg, Terms) -> Term | undefined
                     when Arg :: binary(), Terms :: map(), Term :: #{binary() => term()} | undefined.

Find a named argument in a query terms list or map.

lookup_qarg(Arg, Terms, Default)

-spec lookup_qarg(Arg, Terms, Default) -> Term | Default
                     when
                         Arg :: binary(),
                         Terms :: map(),
                         Default :: term(),
                         Term :: #{binary() => term()}.

lookup_qarg_value(Arg, Terms)

-spec lookup_qarg_value(Arg, Terms) -> TermValue | undefined
                           when Arg :: binary(), Terms :: map(), TermValue :: term().

Find the term value of a named argument in a query terms list or map.

lookup_qarg_value(Arg, Terms, Default)

-spec lookup_qarg_value(Arg, Terms, Default) -> TermValue | Default
                           when Arg :: binary(), Terms :: map(), Default :: term(), TermValue :: term().

Find the term value of a named argument in a query terms list or map. Return the default when the term is not found or doesn't have a value.

map_to_options(Map)

-spec map_to_options(map()) -> search_options().

Map a map with (binary) search options to a search option list.

props_to_map(Props)

-spec props_to_map(list() | map() | undefined) -> #{binary() => term()}.

Change a search props list to a standard query format.

query_(Args, Context)

-spec query_(proplists:proplist() | map(), z:context()) -> [m_rsc:resource_id()].

Given a query as proplist or map, return all results.

reformat_sql_query(Search_sql, Options, Context)

-spec reformat_sql_query(#search_sql{select :: iodata(),
                                     from :: iodata(),
                                     where :: iodata(),
                                     order :: iodata(),
                                     group_by :: iodata(),
                                     limit :: term(),
                                     tables :: list(),
                                     args :: list(),
                                     cats :: list(),
                                     cats_exclude :: list(),
                                     cats_exact :: list(),
                                     run_func :: function() | undefined,
                                     post_func ::
                                         fun((#search_result{search_name :: binary() | atom(),
                                                             search_args :: map() | proplists:proplist(),
                                                             result :: list(),
                                                             page :: pos_integer(),
                                                             pagelen :: pos_integer() | undefined,
                                                             options :: z_search:search_options(),
                                                             total :: non_neg_integer() | undefined,
                                                             pages :: non_neg_integer() | undefined,
                                                             is_total_estimated :: boolean(),
                                                             next :: pos_integer() | false,
                                                             prev :: pos_integer(),
                                                             facets :: #{binary() => map()} | undefined},
                                              #search_sql{},
                                              z:context()) ->
                                                 #search_result{search_name :: binary() | atom(),
                                                                search_args ::
                                                                    map() | proplists:proplist(),
                                                                result :: list(),
                                                                page :: pos_integer(),
                                                                pagelen :: pos_integer() | undefined,
                                                                options :: z_search:search_options(),
                                                                total :: non_neg_integer() | undefined,
                                                                pages :: non_neg_integer() | undefined,
                                                                is_total_estimated :: boolean(),
                                                                next :: pos_integer() | false,
                                                                prev :: pos_integer(),
                                                                facets ::
                                                                    #{binary() => map()} | undefined}) |
                                         undefined,
                                     extra :: list(),
                                     assoc :: boolean(),
                                     search_sql_terms :: list() | undefined},
                         search_options(),
                         z:context()) ->
                            #search_sql{select :: iodata(),
                                        from :: iodata(),
                                        where :: iodata(),
                                        order :: iodata(),
                                        group_by :: iodata(),
                                        limit :: term(),
                                        tables :: list(),
                                        args :: list(),
                                        cats :: list(),
                                        cats_exclude :: list(),
                                        cats_exact :: list(),
                                        run_func :: function() | undefined,
                                        post_func ::
                                            fun((#search_result{search_name :: binary() | atom(),
                                                                search_args ::
                                                                    map() | proplists:proplist(),
                                                                result :: list(),
                                                                page :: pos_integer(),
                                                                pagelen :: pos_integer() | undefined,
                                                                options :: z_search:search_options(),
                                                                total :: non_neg_integer() | undefined,
                                                                pages :: non_neg_integer() | undefined,
                                                                is_total_estimated :: boolean(),
                                                                next :: pos_integer() | false,
                                                                prev :: pos_integer(),
                                                                facets ::
                                                                    #{binary() => map()} | undefined},
                                                 #search_sql{},
                                                 z:context()) ->
                                                    #search_result{search_name :: binary() | atom(),
                                                                   search_args ::
                                                                       map() | proplists:proplist(),
                                                                   result :: list(),
                                                                   page :: pos_integer(),
                                                                   pagelen :: pos_integer() | undefined,
                                                                   options :: z_search:search_options(),
                                                                   total ::
                                                                       non_neg_integer() | undefined,
                                                                   pages ::
                                                                       non_neg_integer() | undefined,
                                                                   is_total_estimated :: boolean(),
                                                                   next :: pos_integer() | false,
                                                                   prev :: pos_integer(),
                                                                   facets ::
                                                                       #{binary() => map()} | undefined}) |
                                            undefined,
                                        extra :: list(),
                                        assoc :: boolean(),
                                        search_sql_terms :: list() | undefined}.

Inject the ACL checks in the SQL query.

search(Search, Context)

This function is deprecated. use search/5. 
-spec search({atom() | binary(), proplists:proplist() | map()}, z:context()) ->
                #search_result{search_name :: binary() | atom(),
                               search_args :: map() | proplists:proplist(),
                               result :: list(),
                               page :: pos_integer(),
                               pagelen :: pos_integer() | undefined,
                               options :: z_search:search_options(),
                               total :: non_neg_integer() | undefined,
                               pages :: non_neg_integer() | undefined,
                               is_total_estimated :: boolean(),
                               next :: pos_integer() | false,
                               prev :: pos_integer(),
                               facets :: #{binary() => map()} | undefined}.

Search with the question and return the results

search(Search, MaxRows, Context)

This function is deprecated. use search/5. 
-spec search(search_query(), search_offset() | undefined, z:context()) ->
                #search_result{search_name :: binary() | atom(),
                               search_args :: map() | proplists:proplist(),
                               result :: list(),
                               page :: pos_integer(),
                               pagelen :: pos_integer() | undefined,
                               options :: z_search:search_options(),
                               total :: non_neg_integer() | undefined,
                               pages :: non_neg_integer() | undefined,
                               is_total_estimated :: boolean(),
                               next :: pos_integer() | false,
                               prev :: pos_integer(),
                               facets :: #{binary() => map()} | undefined}.

Perform the named search and its arguments

search(Name, Args, Page, PageLen, Context)

-spec search(Name, Args, Page, PageLen, Context) -> Result
                when
                    Name :: binary(),
                    Args :: map() | proplists:proplist() | undefined,
                    Page :: pos_integer() | undefined,
                    PageLen :: pos_integer() | undefined,
                    Context :: z:context(),
                    Result ::
                        #search_result{search_name :: binary() | atom(),
                                       search_args :: map() | proplists:proplist(),
                                       result :: list(),
                                       page :: pos_integer(),
                                       pagelen :: pos_integer() | undefined,
                                       options :: z_search:search_options(),
                                       total :: non_neg_integer() | undefined,
                                       pages :: non_neg_integer() | undefined,
                                       is_total_estimated :: boolean(),
                                       next :: pos_integer() | false,
                                       prev :: pos_integer(),
                                       facets :: #{binary() => map()} | undefined}.

Perform a named search with arguments.

search(Name, Args, Page, PageLen, Options, Context)

-spec search(Name, Args, Page, PageLen, Options, Context) -> Result
                when
                    Name :: binary(),
                    Args :: map() | proplists:proplist() | undefined,
                    Page :: pos_integer() | undefined,
                    PageLen :: pos_integer() | undefined,
                    Options :: map(),
                    Context :: z:context(),
                    Result ::
                        #search_result{search_name :: binary() | atom(),
                                       search_args :: map() | proplists:proplist(),
                                       result :: list(),
                                       page :: pos_integer(),
                                       pagelen :: pos_integer() | undefined,
                                       options :: z_search:search_options(),
                                       total :: non_neg_integer() | undefined,
                                       pages :: non_neg_integer() | undefined,
                                       is_total_estimated :: boolean(),
                                       next :: pos_integer() | false,
                                       prev :: pos_integer(),
                                       facets :: #{binary() => map()} | undefined}.

Perform a named search with arguments.

search_pager(Query, Page, Context)

This function is deprecated. use search/5. 
-spec search_pager(Query, Page, Context) -> Result
                      when
                          Query :: search_query(),
                          Page :: pos_integer(),
                          Context :: z:context(),
                          Result ::
                              #search_result{search_name :: binary() | atom(),
                                             search_args :: map() | proplists:proplist(),
                                             result :: list(),
                                             page :: pos_integer(),
                                             pagelen :: pos_integer() | undefined,
                                             options :: z_search:search_options(),
                                             total :: non_neg_integer() | undefined,
                                             pages :: non_neg_integer() | undefined,
                                             is_total_estimated :: boolean(),
                                             next :: pos_integer() | false,
                                             prev :: pos_integer(),
                                             facets :: #{binary() => map()} | undefined}.

Search items and handle the paging. Uses the default page length.

search_pager(Query, Page, PageLen, Context)

-spec search_pager(Query, Page, PageLen, Context) -> Result
                      when
                          Query :: search_query(),
                          Page :: pos_integer() | undefined,
                          PageLen :: pos_integer() | undefined,
                          Context :: z:context(),
                          Result ::
                              #search_result{search_name :: binary() | atom(),
                                             search_args :: map() | proplists:proplist(),
                                             result :: list(),
                                             page :: pos_integer(),
                                             pagelen :: pos_integer() | undefined,
                                             options :: z_search:search_options(),
                                             total :: non_neg_integer() | undefined,
                                             pages :: non_neg_integer() | undefined,
                                             is_total_estimated :: boolean(),
                                             next :: pos_integer() | false,
                                             prev :: pos_integer(),
                                             facets :: #{binary() => map()} | undefined}.

Search items and handle the paging. This fetches extra rows beyond the requested rows to ensure that the pager has the information for the "next page" options. The number of extra rows depends on the current page, more for page 1, less for later pages.

search_result(Result, Limit, Context)

-spec search_result(Result, search_offset(), Context) ->
                       #search_result{search_name :: binary() | atom(),
                                      search_args :: map() | proplists:proplist(),
                                      result :: list(),
                                      page :: pos_integer(),
                                      pagelen :: pos_integer() | undefined,
                                      options :: z_search:search_options(),
                                      total :: non_neg_integer() | undefined,
                                      pages :: non_neg_integer() | undefined,
                                      is_total_estimated :: boolean(),
                                      next :: pos_integer() | false,
                                      prev :: pos_integer(),
                                      facets :: #{binary() => map()} | undefined}
                       when
                           Result ::
                               list() |
                               #search_result{search_name :: binary() | atom(),
                                              search_args :: map() | proplists:proplist(),
                                              result :: list(),
                                              page :: pos_integer(),
                                              pagelen :: pos_integer() | undefined,
                                              options :: z_search:search_options(),
                                              total :: non_neg_integer() | undefined,
                                              pages :: non_neg_integer() | undefined,
                                              is_total_estimated :: boolean(),
                                              next :: pos_integer() | false,
                                              prev :: pos_integer(),
                                              facets :: #{binary() => map()} | undefined} |
                               #search_sql{select :: iodata(),
                                           from :: iodata(),
                                           where :: iodata(),
                                           order :: iodata(),
                                           group_by :: iodata(),
                                           limit :: term(),
                                           tables :: list(),
                                           args :: list(),
                                           cats :: list(),
                                           cats_exclude :: list(),
                                           cats_exact :: list(),
                                           run_func :: function() | undefined,
                                           post_func ::
                                               fun((#search_result{search_name :: binary() | atom(),
                                                                   search_args ::
                                                                       map() | proplists:proplist(),
                                                                   result :: list(),
                                                                   page :: pos_integer(),
                                                                   pagelen :: pos_integer() | undefined,
                                                                   options :: z_search:search_options(),
                                                                   total ::
                                                                       non_neg_integer() | undefined,
                                                                   pages ::
                                                                       non_neg_integer() | undefined,
                                                                   is_total_estimated :: boolean(),
                                                                   next :: pos_integer() | false,
                                                                   prev :: pos_integer(),
                                                                   facets ::
                                                                       #{binary() => map()} | undefined},
                                                    #search_sql{},
                                                    z:context()) ->
                                                       #search_result{search_name :: binary() | atom(),
                                                                      search_args ::
                                                                          map() | proplists:proplist(),
                                                                      result :: list(),
                                                                      page :: pos_integer(),
                                                                      pagelen ::
                                                                          pos_integer() | undefined,
                                                                      options ::
                                                                          z_search:search_options(),
                                                                      total ::
                                                                          non_neg_integer() | undefined,
                                                                      pages ::
                                                                          non_neg_integer() | undefined,
                                                                      is_total_estimated :: boolean(),
                                                                      next :: pos_integer() | false,
                                                                      prev :: pos_integer(),
                                                                      facets ::
                                                                          #{binary() => map()} |
                                                                          undefined}) |
                                               undefined,
                                           extra :: list(),
                                           assoc :: boolean(),
                                           search_sql_terms :: list() | undefined},
                           Context :: z:context().

Handle a return value from a search function. This can be an intermediate SQL statement that still needs to be augmented with extra ACL checks.