Skip to content

Commit 3181215

Browse files
dplewismontymxb
dplewis
authored and
montymxb
committed
Update JS Docs (#497)
* Update JS Docs * Added aggregate example and typos * Stylistic Changes
1 parent 0a80fd9 commit 3181215

File tree

5 files changed

+364
-1
lines changed

5 files changed

+364
-1
lines changed

‎_includes/js/geopoints.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,38 @@ query.find({
5757
});
5858
</code></pre>
5959

60+
You can query for whether an object lies within or on a polygon of `Parse.GeoPoint` (minimum 3 points):
61+
62+
<pre><code class="javascript">
63+
query.withinPolygon("location", [geoPoint1, geoPoint2, geoPoint3]);
64+
query.find({
65+
success: function(objectsWithGeoPointInPolygon) {
66+
...
67+
}
68+
});
69+
</code></pre>
70+
71+
You can also query for whether an object `Parse.Polygon` contains a `Parse.GeoPoint`:
72+
73+
<pre><code class="javascript">
74+
const p1 = [[0,0], [0,1], [1,1], [1,0]];
75+
const p2 = [[0,0], [0,2], [2,2], [2,0]];
76+
const p3 = [[10,10], [10,15], [15,15], [15,10], [10,10]];
77+
78+
const polygon1 = new Parse.Polygon(p1);
79+
const polygon2 = new Parse.Polygon(p2);
80+
const polygon3 = new Parse.Polygon(p3);
81+
82+
const point = new Parse.GeoPoint(0.5, 0.5);
83+
const query = new Parse.Query(TestObject);
84+
query.polygonContains('polygon', point);
85+
query.find({
86+
success: function(results) {
87+
// objects contains polygon1 and polygon2
88+
}
89+
});
90+
</code></pre>
91+
6092
## Caveats
6193

6294
At the moment there are a couple of things to watch out for:

‎_includes/js/queries.md

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,39 @@ The above example will match any `BarbecueSauce` objects where the value in the
205205

206206
Queries that have regular expression constraints are very expensive, especially for classes with over 100,000 records. Parse restricts how many such operations can be run on a particular app at any given time.
207207

208+
### Full Text Search
209+
210+
You can use `fullText` for efficient search capabilities. Text indexes are automatically created for you. Your strings are turned into tokens for fast searching.
211+
212+
* Note: Full Text Search can be resource intensive. Ensure the cost of using indexes is worth the benefit, see [storage requirements & performance costs of text indexes.](https://docs.mongodb.com/manual/core/index-text/#storage-requirements-and-performance-costs).
213+
214+
* Parse Server 2.5.0+
215+
216+
<pre><code class="javascript">
217+
var query = new Parse.Query(BarbecueSauce);
218+
query.fullText('name', 'bbq');
219+
</code></pre>
220+
221+
The above example will match any `BarbecueSauce` objects where the value in the "name" String key contains "bbq". For example, both "Big Daddy's BBQ", "Big Daddy's bbq" and "Big BBQ Daddy" will match.
222+
223+
<pre><code class="javascript">
224+
// You can sort by weight / rank. ascending('') and select()
225+
var query = new Parse.Query(BarbecueSauce);
226+
query.fullText('name', 'bbq');
227+
query.ascending('$score');
228+
query.select('$score');
229+
query.find()
230+
.then(function(results) {
231+
// results contains a weight / rank in result.get('score')
232+
})
233+
.catch(function(error) {
234+
// There was an error.
235+
});
236+
</code></pre>
237+
238+
239+
240+
For Case or Diacritic Sensitive search, please use the [REST API](http://docs.parseplatform.org/rest/guide/#queries-on-string-values).
208241

209242
## Relational Queries
210243

@@ -391,3 +424,153 @@ mainQuery.find()
391424
// There was an error.
392425
});
393426
</code></pre>
427+
428+
## Aggregate
429+
430+
Queries can be made using aggregates, allowing you to retrieve objects over a set of input values. The results will not be `Parse.Object`s since you will be aggregating your own fields
431+
432+
* Parse Server 2.7.1+
433+
* `MasterKey` is Required.
434+
435+
Aggregates use stages to filter results by piping results from one stage to the next.
436+
437+
You can create a pipeline using an Array or an Object.
438+
439+
The following example is a pipeline similar to `distinct` grouping by name field.
440+
441+
<pre><code class="javascript">
442+
var pipelineObject = {
443+
group: { objectId: '$name' }
444+
};
445+
446+
var pipelineArray = [
447+
{ group: { objectId: '$name' } }
448+
];
449+
</code></pre>
450+
451+
For a list of available operators please refer to [Mongo Aggregate Documentation](https://docs.mongodb.com/v3.2/reference/operator/aggregation/).
452+
453+
* Note: Most operations in Mongo Aggregate Documentation will work with Parse Server, but `_id` doesn't exist. Please replace with `objectId`.
454+
455+
Group pipeline is similar to `distinct`.
456+
457+
You can group by a field.
458+
459+
<pre><code class="javascript">
460+
// score is the field. $ before score lets the database know this is a field
461+
var pipeline = [
462+
group: { objectId: '$score' }
463+
];
464+
var query = new Parse.Query("User");
465+
query.aggregate(pipeline);
466+
query.find()
467+
.then(function(results) {
468+
// results contains unique score values
469+
})
470+
.catch(function(error) {
471+
// There was an error.
472+
});
473+
</code></pre>
474+
475+
You can apply collective calculations like $sum, $avg, $max, $min.
476+
477+
<pre><code class="javascript">
478+
// total will be a newly created field to hold the sum of score field
479+
var pipeline = [
480+
group: { objectId: null, total: { $sum: '$score' } }
481+
];
482+
var query = new Parse.Query("User");
483+
query.aggregate(pipeline);
484+
query.find()
485+
.then(function(results) {
486+
// results contains sum of score field and stores it in results[0].total
487+
})
488+
.catch(function(error) {
489+
// There was an error.
490+
});
491+
</code></pre>
492+
493+
Project pipeline is similar to `keys` or `select`, add or remove existing fields.
494+
495+
<pre><code class="javascript">
496+
var pipeline = [
497+
project: { name: 1 }
498+
];
499+
var query = new Parse.Query("User");
500+
query.aggregate(pipeline);
501+
query.find()
502+
.then(function(results) {
503+
// results contains only name field
504+
})
505+
.catch(function(error) {
506+
// There was an error.
507+
});
508+
</code></pre>
509+
510+
Match pipeline is similar to `equalTo`.
511+
512+
<pre><code class="javascript">
513+
var pipeline = [
514+
{ match: { name: 'BBQ' } }
515+
];
516+
var query = new Parse.Query("User");
517+
query.aggregate(pipeline);
518+
query.find()
519+
.then(function(results) {
520+
// results contains name that matches 'BBQ'
521+
})
522+
.catch(function(error) {
523+
// There was an error.
524+
});
525+
</code></pre>
526+
527+
You can match by comparison.
528+
529+
<pre><code class="javascript">
530+
var pipeline = [
531+
match: { score: { $gt: 15 } }
532+
];
533+
var query = new Parse.Query("User");
534+
query.aggregate(pipeline);
535+
query.find()
536+
.then(function(results) {
537+
// results contains score greater than 15
538+
})
539+
.catch(function(error) {
540+
// There was an error.
541+
});
542+
</code></pre>
543+
544+
## Distinct
545+
546+
Queries can be made using distinct, allowing you find unique values for a specified field.
547+
548+
* Parse Server 2.7.1+
549+
* `MasterKey` is required.
550+
551+
<pre><code class="javascript">
552+
var query = new Parse.Query("User");
553+
query.distinct("age");
554+
query.find()
555+
.then(function(results) {
556+
// results contains unique age
557+
})
558+
.catch(function(error) {
559+
// There was an error.
560+
});
561+
</code></pre>
562+
563+
You can also restrict results by using `equalTo`.
564+
565+
<pre><code class="javascript">
566+
var query = new Parse.Query("User");
567+
query.equalTo("name", "foo");
568+
query.distinct("age");
569+
query.find()
570+
.then(function(results) {
571+
// results contains unique age where name is foo
572+
})
573+
.catch(function(error) {
574+
// There was an error.
575+
});
576+
</code></pre>

‎_includes/js/schema.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Schema
2+
3+
Schema is the structure representing classes in your app. You can use the schema
4+
of an app to verify operations in a unit test, generate test data, generate test
5+
classes and then clean up after tests. The schema API can also be used to create
6+
custom views of your data. We use the schema API to display column names and
7+
types in the databrowser.
8+
9+
This API allows you to access the schemas of your app.
10+
11+
* Parse Server 2.7.1+
12+
* `MasterKey` is required.
13+
14+
Schema will return an object similar to the following:
15+
16+
<pre><code class="javascript">
17+
{
18+
className: 'MyClass',
19+
fields: {
20+
// Default fields
21+
ACL: {type: 'ACL'},
22+
createdAt: {type: 'Date'},
23+
updatedAt: {type: 'Date'},
24+
objectId: {type: 'String'},
25+
// Custom fields
26+
aNumber: {type: 'Number'},
27+
aString: {type: 'String'},
28+
aBool: {type: 'Boolean'},
29+
aDate: {type: 'Date'},
30+
aObject: {type: 'Object'},
31+
aArray: {type: 'Array'},
32+
aGeoPoint: {type: 'GeoPoint'},
33+
aPolygon: {type: 'Polygon'},
34+
aFile: {type: 'File'}
35+
},
36+
classLevelPermissions: {
37+
find: {
38+
'*': true
39+
},
40+
create: {
41+
'*': true
42+
},
43+
get: {
44+
'*': true
45+
},
46+
update: {
47+
'*': true
48+
},
49+
addField: {
50+
'*': true
51+
},
52+
delete: {
53+
'*': true
54+
}
55+
},
56+
indexes: {
57+
indexName: { aString: 1 },
58+
}
59+
}
60+
</code></pre>
61+
62+
Direct manipulation of the classes that are on your server is possible through ParseSchema. Although fields and classes can be automatically generated (the latter assuming client class creation is enabled) ParseSchema gives you explicit control over these classes and their fields.
63+
64+
*With great power comes great responsibility. Altering the schema directly should be done with care, you can't go back to retrieve data if you remove a field and it's associated values.*
65+
66+
<pre><code class="javascript">
67+
// create an instance to manage your class
68+
const mySchema = new Parse.Schema('MyClass');
69+
70+
// gets the current schema data
71+
mySchema.get();
72+
73+
// returns schema for all classes
74+
Parse.Schema.all()
75+
76+
// add any # of fields, without having to create any objects
77+
mySchema
78+
.addString('stringField')
79+
.addNumber('numberField')
80+
.addBoolean('booleanField')
81+
.addDate('dateField')
82+
.addFile('fileField')
83+
.addGeoPoint('geoPointField')
84+
.addPolygon('polygonField')
85+
.addArray('arrayField')
86+
.addObject('objectField')
87+
.addPointer('pointerField', '_User')
88+
.addRelation('relationField', '_User');
89+
90+
// new types can be added as they are available
91+
mySchema.addField('newField', 'ANewDataType')
92+
93+
// save/update this schema to persist your field changes
94+
mySchema.save().then((result) => {
95+
// returns save new schema
96+
});
97+
// or
98+
mySchema.update().then((result) => {
99+
// updates existing schema
100+
});
101+
</code></pre>
102+
103+
Assuming you want to remove a field you can simply call `deleteField` and `save/update` to clear it out.
104+
105+
<pre><code class="javascript">
106+
mySchema.deleteField('stringField');
107+
mySchema.save();
108+
// or for an existing schema...
109+
mySchema.update();
110+
</code></pre>
111+
112+
## Indexes
113+
114+
Indexes support efficient execution of queries from the database. Keep in mind that the `masterKey` is required for these operations, so be sure it's set in your initialization code before you use this feature.
115+
116+
<pre><code class="javascript">
117+
// To add an index, the field must exist before you create an index
118+
mySchema.addString('stringField');
119+
const index = {
120+
stringField: 1
121+
};
122+
mySchema.addIndex('stringFieldIndex', index);
123+
mySchema.save().then((result) => {
124+
// returns schema including index stringFieldIndex and field stringField
125+
});
126+
127+
// Delete an index
128+
testSchema.deleteIndex('indexName');
129+
mySchema.save().then((result) => {
130+
// returns schema without indexName index
131+
});
132+
133+
// If indexes exist, you can retrieve them
134+
mySchema.get().then((result) => {
135+
// result.indexes
136+
});
137+
</code></pre>
138+
139+
## Purge
140+
141+
All objects can be purged from a schema (class) via purge. But *be careful*! This can be considered an irreversible action. Only do this if you really need to delete all objects from a class, such as when you need to delete the class (as in the code example above).
142+
143+
<pre><code class="javascript">
144+
// delete all objects in the schema
145+
mySchema.purge();
146+
</code></pre>
147+

‎_includes/rest/schemas.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ types in the databrowser.
99
This API allows you to access the schemas of your app.
1010
Note: This API can be only accessed using the `master key`.
1111

12-
* Starting with Parse-Server 3.0 Index support added.
12+
* Starting with Parse Server 2.7.1 Index support added.
1313

1414
## Fetch the schema
1515
To fetch the Schema for all the classes of your app, run:

‎js.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ sections:
2222
- "js/analytics.md"
2323
- "common/data.md"
2424
- "common/relations.md"
25+
- "js/schema.md"
2526
- "js/handling-errors.md"
2627
- "common/security.md"
2728
- "common/performance.md"

0 commit comments

Comments
 (0)