forked from Automattic/mongoose
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathquery_casting.html
More file actions
140 lines (118 loc) · 16.2 KB
/
query_casting.html
File metadata and controls
140 lines (118 loc) · 16.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose v5.6.4-pre: Mongoose Tutorials: Query Casting</title><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="stylesheet" href="https://unpkg.com/[email protected]/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans"><link rel="stylesheet" href="/docs/css/github.css"><link rel="stylesheet" href="/docs/css/mongoose5.css"><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="manifest" href="images/favicon/manifest.json"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="images/favicon/ms-icon-144x144.png"><meta name="theme-color" content="#ffffff"><link rel="stylesheet" href="/docs/css/inlinecpc.css"><script type="text/javascript" src="/docs/js/native.js"></script><style>p { line-height: 1.5em }
</style></head><body><div id="layout"><div id="mobile-menu"><a class="menu-link" id="menuLink" href="#menu"><span></span></a><div id="mobile-logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png"><span class="logo-text">mongoose</span></a></div></div><div id="menu"><div class="pure-menu"><div class="pure-menu-heading" id="logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png"><span class="logo-text">mongoose</span></a></div><ul class="pure-menu-list" id="navbar"><li class="pure-menu-horizontal pure-menu-item pure-menu-has-children pure-menu-allow-hover version"><a class="pure-menu-link" href="#">Version 5.6.4-pre</a><ul class="pure-menu-children"><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/4.x">Version 4.13.19</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/3.8.x">Version 3.8.40</a></li></ul></li><li class="pure-menu-item search"><input id="search-input-nav" type="text" placeholder="Search"><button id="search-button-nav"><img src="/docs/images/search.svg"></button></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/index.html">Quick Start</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/guides.html">Guides</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/guide.html">Schemas</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/schematypes.html">SchemaTypes</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/connections.html">Connections</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/models.html">Models</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/documents.html">Documents</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/subdocs.html">Subdocuments</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/queries.html">Queries</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/validation.html">Validation</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/middleware.html">Middleware</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/populate.html">Populate</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/discriminators.html">Discriminators</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/plugins.html">Plugins</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/api.html">API</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/mongoose.html">Mongoose</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/schema.html">Schema</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/connection.html">Connection</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/document.html">Document</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/model.html">Model</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/query.html">Query</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/aggregate.html">Aggregate</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/schematype.html">SchemaType</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/virtualtype.html">VirtualType</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/compatibility.html">Version Compatibility</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/faq.html">FAQ</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/further_reading.html">Further Reading</a></li></ul><div class="cpc-ad"><script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=mongoosejscom" id="_carbonads_js"></script></div></div></div><div class="container"><div id="content"><h1 id="query-casting">Query Casting</h1>
<script>
_native.init("CK7DT53U",{
targetClass: 'native-inline'
});
</script>
<div class="native-inline">
<a href="#native_link#"><span class="sponsor">Sponsor</span> #native_company# — #native_desc#</a>
</div>
<p>The first parameter to <a href="https://mongoosejs.com/docs/api.html#model_Model.find"><code>Model.find()</code></a>, <a href="https://mongoosejs.com/docs/api.html#query_Query-find"><code>Query#find()</code></a>, <a href="https://mongoosejs.com/docs/api.html#model_Model.findOne"><code>Model.findOne()</code></a>, etc. is called <code>filter</code>. In older content this parameter is sometimes called <code>query</code> or <code>conditions</code>. For example:</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> query = Character.find({ name: <span class="hljs-string">'Jean-Luc Picard'</span> });
query.getFilter(); <span class="hljs-comment">// `{ name: 'Jean-Luc Picard' }`</span>
<span class="hljs-comment">// Subsequent chained calls merge new properties into the filter</span>
query.find({ age: { $gt: <span class="hljs-number">50</span> } });
query.getFilter(); <span class="hljs-comment">// `{ name: 'Jean-Luc Picard', age: { $gt: 50 } }`</span></code></pre>
<p>When you execute the query using <a href="https://mongoosejs.com/docs/api.html#query_Query-exec"><code>Query#exec()</code></a> or <a href="https://mongoosejs.com/docs/api.html#query_Query-then"><code>Query#then()</code></a>, Mongoose <em>casts</em> the filter to match your schema.</p>
<pre><code class="language-javascript"><span class="hljs-comment">// Note that `_id` and `age` are strings. Mongoose will cast `_id` to</span>
<span class="hljs-comment">// a MongoDB ObjectId and `age.$gt` to a number.</span>
<span class="hljs-keyword">const</span> query = Character.findOne({
_id: <span class="hljs-string">'5cdc267dd56b5662b7b7cc0c'</span>,
age: { $gt: <span class="hljs-string">'50'</span> }
});
<span class="hljs-comment">// `{ _id: '5cdc267dd56b5662b7b7cc0c', age: { $gt: '50' } }`</span>
<span class="hljs-comment">// Query hasn't been executed yet, so Mongoose hasn't casted the filter.</span>
query.getFilter();
<span class="hljs-keyword">const</span> doc = <span class="hljs-keyword">await</span> query.exec();
doc.name; <span class="hljs-comment">// "Jean-Luc Picard"</span>
<span class="hljs-comment">// Mongoose casted the filter, so `_id` became an ObjectId and `age.$gt`</span>
<span class="hljs-comment">// became a number.</span>
query.getFilter()._id <span class="hljs-keyword">instanceof</span> mongoose.Types.ObjectId; <span class="hljs-comment">// true</span>
<span class="hljs-keyword">typeof</span> query.getFilter().age.$gt === <span class="hljs-string">'number'</span>; <span class="hljs-comment">// true</span></code></pre>
<p>If Mongoose fails to cast the filter to your schema, your query will throw a <code>CastError</code>.</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> query = Character.findOne({ age: { $lt: <span class="hljs-string">'not a number'</span> } });
<span class="hljs-keyword">const</span> err = <span class="hljs-keyword">await</span> query.exec().then(() => <span class="hljs-literal">null</span>, err => err);
err <span class="hljs-keyword">instanceof</span> mongoose.CastError; <span class="hljs-comment">// true</span>
<span class="hljs-comment">// Cast to number failed for value "not a number" at path "age" for</span>
<span class="hljs-comment">// model "Character"</span>
err.message;</code></pre>
<h2 id="the-strictquery-option">The <code>strictQuery</code> Option</h2>
<p>By default, Mongoose does <strong>not</strong> cast filter properties that aren't in your schema.</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> query = Character.findOne({ notInSchema: { $lt: <span class="hljs-string">'not a number'</span> } });
<span class="hljs-comment">// No error because `notInSchema` is not defined in the schema</span>
<span class="hljs-keyword">await</span> query.exec();</code></pre>
<p>You can configure this behavior using the <a href="https://mongoosejs.com/docs/guide.html#strictQuery"><code>strictQuery</code> option for schemas</a>. This option is analagous to the <a href="https://mongoosejs.com/docs/guide.html#strict"><code>strict</code> option</a>. Setting <code>strictQuery</code> to <code>true</code> removes non-schema properties from the filter:</p>
<pre><code class="language-javascript">mongoose.deleteModel(<span class="hljs-string">'Character'</span>);
<span class="hljs-keyword">const</span> schema = <span class="hljs-keyword">new</span> mongoose.Schema({ name: <span class="hljs-built_in">String</span>, age: <span class="hljs-built_in">Number</span> }, {
strictQuery: <span class="hljs-literal">true</span>
});
Character = mongoose.model(<span class="hljs-string">'Character'</span>, schema);
<span class="hljs-keyword">const</span> query = Character.findOne({ notInSchema: { $lt: <span class="hljs-string">'not a number'</span> } });
<span class="hljs-keyword">await</span> query.exec();
query.getFilter(); <span class="hljs-comment">// Empty object `{}`, Mongoose removes `notInSchema`</span></code></pre>
<p>To make Mongoose throw an error if your <code>filter</code> has a property that isn't in the schema, set <code>strictQuery</code> to <code>'throw'</code>:</p>
<pre><code class="language-javascript">mongoose.deleteModel(<span class="hljs-string">'Character'</span>);
<span class="hljs-keyword">const</span> schema = <span class="hljs-keyword">new</span> mongoose.Schema({ name: <span class="hljs-built_in">String</span>, age: <span class="hljs-built_in">Number</span> }, {
strictQuery: <span class="hljs-string">'throw'</span>
});
Character = mongoose.model(<span class="hljs-string">'Character'</span>, schema);
<span class="hljs-keyword">const</span> query = Character.findOne({ notInSchema: { $lt: <span class="hljs-string">'not a number'</span> } });
<span class="hljs-keyword">const</span> err = <span class="hljs-keyword">await</span> query.exec().then(() => <span class="hljs-literal">null</span>, err => err);
err.name; <span class="hljs-comment">// 'StrictModeError'</span>
<span class="hljs-comment">// Path "notInSchema" is not in schema and strictQuery is 'throw'.</span>
err.message;</code></pre>
<h2 id="implicit-in">Implicit <code>$in</code></h2>
<p>Because of schemas, Mongoose knows what types fields should be, so it can provide some neat syntactic sugar. For example, if you forget to put <a href="https://docs.mongodb.com/manual/reference/operator/query/in/"><code>$in</code></a> on a non-array field, Mongoose will add <code>$in</code> for you.</p>
<pre><code class="language-javascript"><span class="hljs-comment">// Normally wouldn't find anything because `name` is a string, but</span>
<span class="hljs-comment">// Mongoose automatically inserts `$in`</span>
<span class="hljs-keyword">const</span> query = Character.findOne({ name: [<span class="hljs-string">'Jean-Luc Picard'</span>, <span class="hljs-string">'Will Riker'</span>] });
<span class="hljs-keyword">const</span> doc = <span class="hljs-keyword">await</span> query.exec();
doc.name; <span class="hljs-comment">// "Jean-Luc Picard"</span>
<span class="hljs-comment">// `{ name: { $in: ['Jean-Luc Picard', 'Will Riker'] } }`</span>
query.getFilter();</code></pre>
</div></div><script type="text/javascript">var xhr = new XMLHttpRequest();
xhr.open('POST', 'https://g0a3nbw0xa.execute-api.us-east-1.amazonaws.com/prod/track', true);
xhr.setRequestHeader('Content-Type', 'application/json');
xhr.onreadystatechange = function() {};
xhr.send(JSON.stringify({
path: window.location.pathname,
hostname: window.location.hostname,
hash: window.location.hash
}));</script><script type="text/javascript" src="/docs/js/navbar-search.js"></script><script type="text/javascript">(function (window, document) {
var layout = document.getElementById('layout'),
menu = document.getElementById('menu'),
menuLink = document.getElementById('menuLink'),
content = document.getElementById('content');
function toggleClass(element, className) {
var classes = element.className.split(/\s+/),
length = classes.length,
i = 0;
for(; i < length; i++) {
if (classes[i] === className) {
classes.splice(i, 1);
break;
}
}
// The className is not found
if (length === classes.length) {
classes.push(className);
}
element.className = classes.join(' ');
}
function toggleAll(e) {
var active = 'active';
e.preventDefault();
toggleClass(layout, active);
toggleClass(menu, active);
toggleClass(menuLink, active);
}
menuLink.onclick = function (e) {
toggleAll(e);
};
content.onclick = function(e) {
if (menu.className.indexOf('active') !== -1) {
toggleAll(e);
}
};
}(this, this.document));</script></div></body></html>