Class: Contentstack::Query

Inherits:
Object
  • Object
show all
Defined in:
lib/contentstack/query.rb

Overview

A class that defines a query that is used to query for Entry instance.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(content_type) ⇒ Contentstack::Query

Initialize the Query instance Example:

@query   = @stack.content_type('blog').query
@entries = @query.where('author', 'John Doe').fetch

Parameters:

  • content_type (String) 


24
25
26
27
28
29
30
31
32
33
 
# File 'lib/contentstack/query.rb', line 24

def initialize(content_type)
  @content_type = content_type
  @query = {
    query: "{}",
    include_count: false,
    skip: 0,
    count: 10,
    desc: 'created_at'
  }
end

Instance Attribute Details

#content_type ⇒ Object (readonly)

Returns the value of attribute content_type.



14
 
# File 'lib/contentstack/query.rb', line 14

attr_reader :query, :content_type

#query ⇒ Object (readonly)

Returns the value of attribute query.




# File 'lib/contentstack/query.rb', line 8

Instance Method Details

#add_query(field_uid, value) ⇒ Contentstack::Query

Add a custom query against specified key. Example:

@query   = @stack.content_type('blog').query
@query.add_query('author', "Jane Doe")

Parameters:

  • field_uid (String)
  • value (String/Number/Boolean/Hash)

Returns:



44
45
46
 
# File 'lib/contentstack/query.rb', line 44

def add_query(field_uid, value)
  add_query_hash({:"#{field_uid}" => value})
end

#and(queries) ⇒ Contentstack::Query

Combines all the queries together using AND operator.

Each query should be an instance of the Contentstack::Query class, and belong to the same ‘content_type` Example:

@query1 = @stack.content_type('category').query
@query1.where('title', 'Electronics')

@query2 = @stack.content_type('category').query
@query2.regex('description', '.*Electronics.*')

query_array = [@query1, @query2]

@query = @stack.content_type('category').query
@query.and(query_array)

Parameters:

  • queries (Array) —

    Array of instances of the Query class

Returns:



140
141
142
143
 
# File 'lib/contentstack/query.rb', line 140

def and(queries)
  add_query_hash({"$and" => concat_queries(queries)})
  self
end

#ascending(field_uid) ⇒ Contentstack::Query

Sort the results in ascending order with the given key. Sort the returned entries in ascending order of the provided key.

Example

@query = @stack.content_type('category').query
@query.ascending

Parameters:

  • field_uid (String) —

    The key to order by

Returns:



373
374
375
376
377
 
# File 'lib/contentstack/query.rb', line 373

def ascending(field_uid)
  @query.delete(:desc)
  @query[:asc] = field_uid
  self
end

#contained_in(field_uid, values) ⇒ Contentstack::Query Also known as: in

Add a constraint to the query that requires a particular key’s entry to be contained in the provided array.

Example 1 - Array Equals Operator Within Group

@query = @stack.content_type('category').query
@query.contained_in("title", ["Electronics", "Apparel"])

Example 2 - Array Equals Operator Within Modular Blocks

@query = @stack.content_type('category').query
@query.contained_in("additional_info.deals.deal_name", ["Christmas Deal", "Summer Deal"])

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • values (String) —

    The possible values for the key’s object

Returns:



261
262
263
264
 
# File 'lib/contentstack/query.rb', line 261

def contained_in(field_uid, values)
  add_query_hash({:"#{field_uid}" => {"$in" => values}})
  self
end

#count ⇒ Integer

Retrieve only count of entries in result.

Example

@query = @stack.content_type('category').query
@query.count

Returns:

  • (Integer) 


334
335
336
337
 
# File 'lib/contentstack/query.rb', line 334

def count
  include_count
  fetch.count
end

#descending(field_uid) ⇒ Contentstack::Query

Sort the results in descending order with the given key. Sort the returned entries in descending order of the provided key.

Example

@query = @stack.content_type('category').query
@query.descending

Parameters:

  • field_uid (String) —

    The key to order by

Returns:



389
390
391
392
393
 
# File 'lib/contentstack/query.rb', line 389

def descending(field_uid)
  @query.delete(:asc)
  @query[:desc] = field_uid
  self
end

#except(fields, fields_with_base = nil) ⇒ Contentstack::Query

Specifies list of field uids that would be ‘excluded’ from the response.

Example

# Exclude 'description' field in response
@query = @stack.content_type('category').query
@query.except(['description'])

# Query product and exclude the 'description' from category reference
@query = @stack.content_type('product').query
@query.include_reference('category')
      .except('category', ['description'])

Parameters:

  • fields (Array) —

    Array of field uid which get ‘excluded’ from the response.

  • fields_with_base (Array) (defaults to: nil) —

    Can be used to denote ‘except’ fields of the reference class

Returns:



456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'lib/contentstack/query.rb', line 456

def except(fields, fields_with_base=nil)
  q = {}
  if [Array, String].include?(fields_with_base.class)
    fields_with_base = [fields_with_base] if fields_with_base.class == String
    q[fields.to_sym] = fields_with_base
  else
    fields = [fields] if fields.class == String
    q = {BASE: fields}
  end

  @query[:except] = q
  self
end

#exists?(field_uid) ⇒ Contentstack::Query

Add a constraint that requires, a specified key exists in response. Example:

@query = @stack.content_type('product').query
@query.exists?('product_image') # only fetch products which have a `product_image`

Parameters:

  • field_uid (String) —

    The key to be constrained.

Returns:



105
106
107
 
# File 'lib/contentstack/query.rb', line 105

def exists?(field_uid)
  add_query_hash({:"#{field_uid}" => {"$exists" => true}})
end

#fetch ⇒ Contentstack::EntryCollection Also known as: find

Execute query

Example

@query = @stack.content_type('product').query
@query.tags(["tag1", "tag2"])
      .fetch

Returns:



619
620
621
622
 
# File 'lib/contentstack/query.rb', line 619

def fetch
  entries = API.fetch_entries(@content_type, @query)
  EntryCollection.new(entries, @content_type)
end

#find_one ⇒ Contentstack::Entry

Execute a Query and get the single matching object

Example

@query = @stack.content_type('product').query
@query.tags(["tag1", "tag2"])
      .find_one

Returns:



633
634
635
636
 
# File 'lib/contentstack/query.rb', line 633

def find_one
  limit 1
  fetch.first
end

#greater_than(field_uid, value) ⇒ Contentstack::Query

Add a constraint to the query that requires a particular key entry to be greater than the provided value.

Example

@query = @stack.content_type('product').query
@query.greater_than('price', '100')

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • value (String/Number) —

    Value that provides a lower bound

Returns:



211
212
213
214
 
# File 'lib/contentstack/query.rb', line 211

def greater_than(field_uid, value)
  add_query_hash({:"#{field_uid}" => {"$gt" => value}})
  self
end

#greater_than_or_equal(field_uid, value) ⇒ Contentstack::Query

Add a constraint to the query that requires a particular key entry to be greater than or equal to the provided value.

Example

@query = @stack.content_type('product').query
@query.greater_than_or_equal('price', '100')

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • value (String/Number) —

    Value that provides a lower bound

Returns:



227
228
229
230
 
# File 'lib/contentstack/query.rb', line 227

def greater_than_or_equal(field_uid, value)
  add_query_hash({:"#{field_uid}" => {"$gte" => value}})
  self
end

#include(field_uids) ⇒ Contentstack::Query

Returns:



587
588
589
590
591
592
 
# File 'lib/contentstack/query.rb', line 587

def include(field_uids)
  field_uids = [field_uids] if field_uids.class == String
  @query[:include] ||= []
  @query[:include] = @query[:include] | field_uids
  self
end

#include_branch(flag = true) ⇒ Contentstack::Entry

Include the branch for publish content.

Example

@query = @stack.content_type('product').query
@query.include_branch

Returns:



550
551
552
553
 
# File 'lib/contentstack/query.rb', line 550

def include_branch(flag=true)
  @query[:include_branch] = flag
  self
end

#include_content_type(flag = true) ⇒ Contentstack::Query

Include object’s content_type in response

Example

@query = @stack.content_type('product').query
@query.include_content_type

Returns:



523
524
525
526
 
# File 'lib/contentstack/query.rb', line 523

def include_content_type(flag=true)
  @query[:include_content_type] = flag
  self
end

#include_count(flag = true) ⇒ Contentstack::Query

Retrieve count and data of objects in result.

Example

@query = @stack.content_type('category').query
@query.include_count

Returns:



346
347
348
349
 
# File 'lib/contentstack/query.rb', line 346

def include_count(flag=true)
  @query[:include_count] = flag
  self
end

#include_draft(_flag = true) ⇒ Contentstack::Query

Deprecated.

since 0.8.5 The Content Delivery API returns published content only. Unpublished or draft entries are not available through CDA queries. Use Live Preview with the Preview Service, or the Content Management API, to access unpublished content.

Returns:



573
574
575
576
577
578
579
580
581
582
 
# File 'lib/contentstack/query.rb', line 573

def include_draft(_flag=true)
  warn(
    "Contentstack: Query#include_draft is deprecated and has no effect on the Content " \
    "Delivery API, which returns published content only. To preview unpublished entries, " \
    "use Live Preview with the Preview Service. To manage or fetch draft entries, use " \
    "the Content Management API.",
    uplevel: 1
  )
  self
end

#include_embedded_items ⇒ Contentstack::Query

Include Embedded Objects (Entries and Assets) along with entry/entries details.

Example

@query = @stack.content_type('product').query
@query.include_embedded_items

Returns:



563
564
565
566
 
# File 'lib/contentstack/query.rb', line 563

def include_embedded_items()
  @query[:include_embedded_items] = ['BASE']
  self
end

#include_fallback(flag = true) ⇒ Contentstack::Query

Include the fallback locale publish content, if specified locale content is not publish.

Example

@query = @stack.content_type('product').query
@query.include_fallback

Returns:



537
538
539
540
 
# File 'lib/contentstack/query.rb', line 537

def include_fallback(flag=true)
  @query[:include_fallback] = flag
  self
end

#include_metadata(flag = true) ⇒ Contentstack::Query

Retrieve count and data of objects in result.

Example

@query = @stack.content_type('category').query
@query.include_metadata

Returns:



358
359
360
361
 
# File 'lib/contentstack/query.rb', line 358

def include_metadata(flag=true)
  @query[:include_metadata] = flag
  self
end

#include_owner(flag = true) ⇒ Contentstack::Query

Include object owner’s profile in the objects data.

Example

@query = @stack.content_type('product').query
@query.include_owner

Returns:



510
511
512
513
 
# File 'lib/contentstack/query.rb', line 510

def include_owner(flag=true)
  @query[:include_owner] = flag
  self
end

#include_reference(reference_field_uids) ⇒ Contentstack::Query

Add a constraint that requires a particular reference key details.

Example

# Include reference of 'category'
@query = @stack.content_type('product').query
@query.include_reference('category')

# Include reference of 'category' and 'reviews'
@query = @stack.content_type('product').query
@query.include_reference(['category', 'reviews'])

Parameters:

  • reference_field_uids (String/Array) —

    Pass string or array of reference fields that must be included in the response

Returns:



485
486
487
 
# File 'lib/contentstack/query.rb', line 485

def include_reference(reference_field_uids)
  self.include(reference_field_uids)
end

#include_schema(flag = true) ⇒ Contentstack::Query

Include schemas of all returned objects along with objects themselves.

Example

@query = @stack.content_type('product').query
@query.include_schema

Returns:



497
498
499
500
 
# File 'lib/contentstack/query.rb', line 497

def include_schema(flag=true)
  @query[:include_schema] = flag
  self
end

#less_than(field_uid, value) ⇒ Contentstack::Query

Add a constraint to the query that requires a particular key entry to be less than the provided value.

Example

@query = @stack.content_type('product').query
@query.less_than('price', '100')

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • value (String/Number) —

    Value that provides an upper bound

Returns:



179
180
181
182
 
# File 'lib/contentstack/query.rb', line 179

def less_than(field_uid, value)
  add_query_hash({:"#{field_uid}" => {"$lt" => value}})
  self
end

#less_than_or_equal(field_uid, value) ⇒ Contentstack::Query

Add a constraint to the query that requires a particular key entry to be less than or equal to the provided value.

Example

@query = @stack.content_type('product').query
@query.less_than_or_equal('price', '100')

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • value (String/Number) —

    Value that provides an upper bound

Returns:



195
196
197
198
 
# File 'lib/contentstack/query.rb', line 195

def less_than_or_equal(field_uid, value)
  add_query_hash({:"#{field_uid}" => {"$lte" => value}})
  self
end

#limit(count = 10) ⇒ Contentstack::Query

A limit on the number of objects to return.

Example

@query = @stack.content_type('category').query
@query.limit(50)

Parameters:

  • count (Number) (defaults to: 10) —

    of objects to limit in resulset.

Returns:



322
323
324
325
 
# File 'lib/contentstack/query.rb', line 322

def limit(count=10)
  @query[:limit] = count
  self
end

#locale(code) ⇒ Contentstack::Query

Get entries from the specified locale.

Example

Change language method
@query = @stack.content_type('category').query
@query.locale('en-us')

Parameters:

  • code (String) —

    The locale code of the entry

Returns:



405
406
407
408
 
# File 'lib/contentstack/query.rb', line 405

def locale(code)
  @query[:locale] = code
  self
end

#not_contained_in(field_uid, values) ⇒ Contentstack::Query Also known as: not_in

Add a constraint to the query that requires a particular key entry’s value not be contained in the provided array.

Example 1 - Array Not-equals Operator Within Group

@query = @stack.content_type('category').query
@query.not_contained_in("title", ["Electronics", "Apparel"])

Example 2 - Array Not-equals Operator Within Modular Blocks

@query = @stack.content_type('category').query
@query.not_contained_in("additional_info.deals.deal_name", ["Christmas Deal", "Summer Deal"])

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • values (String) —

    The possible values for the key’s object

Returns:



280
281
282
283
 
# File 'lib/contentstack/query.rb', line 280

def not_contained_in(field_uid, values)
  add_query_hash({:"#{field_uid}" => {"$nin" => values}})
  self
end

#not_equal_to(field_uid, value) ⇒ Contentstack::Query

Add a constraint to the query that requires a particular key’s entry to be not equal to the provided value.

Example

@query = @stack.content_type('product').query
@query.not_equal_to('price', '100')

Parameters:

  • field_uid (String) —

    UID of the field for which query should be executed

  • value (String) —

    The object that must not be equaled.

Returns:



242
243
244
245
 
# File 'lib/contentstack/query.rb', line 242

def not_equal_to(field_uid, value)
  add_query_hash({:"#{field_uid}" => {"$ne" => value}})
  self
end

#not_exists?(field_uid) ⇒ Contentstack::Query

Add a constraint that requires, a specified key does not exists in response. Example:

@query = @stack.content_type('product').query
@query.not_exists?('product_image') # only fetch products which do not have a `product_image`

Parameters:

  • field_uid (String) —

    The key to be constrained.

Returns:



117
118
119
120
 
# File 'lib/contentstack/query.rb', line 117

def not_exists?(field_uid)
  add_query_hash({:"#{field_uid}" => {"$exists" => false}})
  self
end

#only(fields, fields_with_base = nil) ⇒ Contentstack::Query

Specifies an array of ‘only’ keys in BASE object that would be ‘included’ in the response.

Example

# Include only title and description field in response
@query = @stack.content_type('category').query
@query.only(['title', 'description'])

# Query product and include only the title and description from category reference
@query = @stack.content_type('product').query
@query.include_reference('category')
      .only('category', ['title', 'description'])

Parameters:

  • fields (Array) —

    Array of the ‘only’ reference keys to be included in response.

  • fields_with_base (Array) (defaults to: nil) —

    Can be used to denote ‘only’ fields of the reference class

Returns:



426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'lib/contentstack/query.rb', line 426

def only(fields, fields_with_base=nil)
  q = {}
  if [Array, String].include?(fields_with_base.class)
    fields_with_base = [fields_with_base] if fields_with_base.class == String
    q[fields.to_sym] = fields_with_base
  else
    fields = [fields] if fields.class == String
    q = {BASE: fields}
  end

  @query[:only] = q
  self
end

#or(queries) ⇒ Contentstack::Query

Combines all the queries together using OR operator.

Each query should be an instance of the Contentstack::Query class, and belong to the same ‘content_type` Example:

@query1 = @stack.content_type('category').query
@query1.where('title', 'Electronics')

@query2 = @stack.content_type('category').query
@query2.where('title', 'Apparel')

query_array = [@query1, @query2]

@query = @stack.content_type('category').query
@query.or(query_array)

Parameters:

  • queries (Array) —

    Array of instances of the Query class

Returns:



163
164
165
166
 
# File 'lib/contentstack/query.rb', line 163

def or(queries)
  add_query_hash({"$or" => concat_queries(queries)})
  self
end

#regex(field_uid, pattern, options = "") ⇒ Contentstack::Query

Add a regular expression constraint for finding string values that match the provided regular expression. This may be slow for large data sets. Example:

@query = @stack.content_type('product').query
@query.regex('title', '.*Mobile.*', 'i') # Search without case sensitivity

Parameters:

  • field_uid (String) —

    The key to be constrained.

  • pattern (String) —

    The regular expression pattern to match.

  • options (String) (defaults to: "") —

    Regex options

Returns:



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/contentstack/query.rb', line 85

def regex(field_uid, pattern, options="")
  hash = {
    "#{field_uid}" => {
      "$regex": pattern
    }
  }

  hash["#{field_uid}"]["$options"] = options if !options.empty? || !options.nil?

  add_query_hash(hash)
end

#remove_query(field_uid) ⇒ Contentstack::Query

Remove provided query key from custom query if exist. Example:

@query   = @stack.content_type('blog').query
@query.remove_query('author')

Parameters:

  • field_uid (String)

Returns:



56
57
58
59
60
61
 
# File 'lib/contentstack/query.rb', line 56

def remove_query(field_uid)
  q = ActiveSupport::JSON.decode(@query[:query])
  q.delete(field_uid)
  @query[:query] = ActiveSupport::JSON.encode(q)
  self
end

#search(text) ⇒ Contentstack::Query

Deprecated.

since version 0.5.0

This method provides only the entries matching the specified value. Example

@query = @stack.content_type('product').query
@query.search("This is an awesome product")

Parameters:

  • text (String) —

    value used to match or compare

Returns:



308
309
310
311
 
# File 'lib/contentstack/query.rb', line 308

def search(text)
  @query[:typeahead] = text
  self
end

#skip(count) ⇒ Contentstack::Query

The number of objects to skip before returning any.

Example

@query = @stack.content_type('category').query
@query.skip(50)

Parameters:

  • count (Number) —

    of objects to skip from resulset.

Returns:



294
295
296
297
 
# File 'lib/contentstack/query.rb', line 294

def skip(count)
  @query[:skip] = count
  self
end

#tags(tags_array) ⇒ Contentstack::Query

Include tags with which to search entries.

Example

@query = @stack.content_type('product').query
@query.tags(["tag1", "tag2"])

Parameters:

  • tags_array (Array) —

    Array of tags using which search must be performed

Returns:



604
605
606
607
 
# File 'lib/contentstack/query.rb', line 604

def tags(tags_array)
  @query[:tags] = tags_array
  self
end

#where(query_hash) ⇒ Contentstack::Query

Add a constraint to fetch all entries that contains given value against specified key. Example:

@query = @stack.content_type('blog').query
@query.where({:author => "Jane Doe"})

Parameters:

  • query_hash (Hash)

Returns:



71
72
73
 
# File 'lib/contentstack/query.rb', line 71

def where(query_hash)
  add_query_hash(query_hash)
end