1<?php
2
3namespace Elastica\Query;
4
5use Elastica\Script\AbstractScript;
6use Elastica\Script\ScriptFields;
7
8/**
9 * Nested query.
10 *
11 * @author Guillaume Affringue <wamania@yahoo.fr>
12 *
13 * @see https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-inner-hits.html
14 */
15class InnerHits extends AbstractQuery
16{
17    /**
18     * {@inheritdoc}
19     */
20    public function toArray()
21    {
22        $array = parent::toArray();
23
24        // if there are no params, it's ok, but ES will throw exception if json
25        // will be like {"top_hits":[]} instead of {"top_hits":{}}
26        if (empty($array['inner_hits'])) {
27            $array['inner_hits'] = new \stdClass();
28        }
29
30        return $array['inner_hits'];
31    }
32
33    /**
34     * The name to be used for the particular inner hit definition in the response.
35     * Useful when multiple inner hits have been defined in a single search request.
36     *
37     * @param string $name
38     *
39     * @return $this
40     */
41    public function setName(string $name): self
42    {
43        return $this->setParam('name', $name);
44    }
45
46    /**
47     * The maximum number of inner matching hits to return per bucket. By default the top three matching hits are returned.
48     *
49     * @param int $size
50     *
51     * @return $this
52     */
53    public function setSize(int $size = 3): self
54    {
55        return $this->setParam('size', $size);
56    }
57
58    /**
59     * The offset from the first result you want to fetch.
60     *
61     * @param int $from
62     *
63     * @return $this
64     */
65    public function setFrom(int $from)
66    {
67        return $this->setParam('from', $from);
68    }
69
70    /**
71     * How the inner matching hits should be sorted. By default the hits are sorted by the score of the main query.
72     *
73     * @param array $sortArgs
74     *
75     * @return $this
76     */
77    public function setSort(array $sortArgs): self
78    {
79        return $this->setParam('sort', $sortArgs);
80    }
81
82    /**
83     * Allows to control how the _source field is returned with every hit.
84     *
85     * @param array|bool $params Fields to be returned or false to disable source
86     *
87     * @return $this
88     */
89    public function setSource($params): self
90    {
91        return $this->setParam('_source', $params);
92    }
93
94    /**
95     * Returns a version for each search hit.
96     *
97     * @param bool $version
98     *
99     * @return $this
100     */
101    public function setVersion(bool $version): self
102    {
103        return $this->setParam('version', $version);
104    }
105
106    /**
107     * Enables explanation for each hit on how its score was computed.
108     *
109     * @param bool $explain
110     *
111     * @return $this
112     */
113    public function setExplain(bool $explain): self
114    {
115        return $this->setParam('explain', $explain);
116    }
117
118    /**
119     * Set script fields.
120     *
121     * @param ScriptFields $scriptFields
122     *
123     * @return $this
124     */
125    public function setScriptFields(ScriptFields $scriptFields): self
126    {
127        return $this->setParam('script_fields', $scriptFields);
128    }
129
130    /**
131     * Adds a Script to the aggregation.
132     *
133     * @param string         $name
134     * @param AbstractScript $script
135     *
136     * @return $this
137     */
138    public function addScriptField(string $name, AbstractScript $script): self
139    {
140        if (!isset($this->_params['script_fields'])) {
141            $this->_params['script_fields'] = new ScriptFields();
142        }
143
144        $this->_params['script_fields']->addScript($name, $script);
145
146        return $this;
147    }
148
149    /**
150     * Sets highlight arguments for the results.
151     *
152     * @param array $highlightArgs
153     *
154     * @return $this
155     */
156    public function setHighlight(array $highlightArgs): self
157    {
158        return $this->setParam('highlight', $highlightArgs);
159    }
160
161    /**
162     * Allows to return the field data representation of a field for each hit.
163     *
164     * @param array $fields
165     *
166     * @return $this
167     */
168    public function setFieldDataFields(array $fields): self
169    {
170        return $this->setParam('docvalue_fields', $fields);
171    }
172}
173