-
-
Notifications
You must be signed in to change notification settings - Fork 515
Update JS Docs #497
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update JS Docs #497
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -57,6 +57,38 @@ query.find({ | |
}); | ||
</code></pre> | ||
|
||
You can query for whether an object lies within / on a polygon of `Parse.GeoPoint` (minimum 3 points): | ||
|
||
<pre><code class="javascript"> | ||
query.withinPolygon("location", [geoPoint1, geoPoint2, geoPoint3]); | ||
query.find({ | ||
success: function(objectsWithGeoPointInPolygon) { | ||
... | ||
} | ||
}); | ||
</code></pre> | ||
|
||
You can query for whether an object `Parse.Polygon` contains a `Parse.GeoPoint`: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Stylistic
|
||
|
||
<pre><code class="javascript"> | ||
const p1 = [[0,0], [0,1], [1,1], [1,0]]; | ||
const p2 = [[0,0], [0,2], [2,2], [2,0]]; | ||
const p3 = [[10,10], [10,15], [15,15], [15,10], [10,10]]; | ||
|
||
const polygon1 = new Parse.Polygon(p1); | ||
const polygon2 = new Parse.Polygon(p2); | ||
const polygon3 = new Parse.Polygon(p3); | ||
|
||
const point = new Parse.GeoPoint(0.5, 0.5); | ||
const query = new Parse.Query(TestObject); | ||
query.polygonContains('polygon', point); | ||
query.find({ | ||
success: function(results) { | ||
// objects contains polygon1 and polygon2 | ||
} | ||
}); | ||
</code></pre> | ||
|
||
## Caveats | ||
|
||
At the moment there are a couple of things to watch out for: | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -205,6 +205,39 @@ The above example will match any `BarbecueSauce` objects where the value in the | |
|
||
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. | ||
|
||
### Full Text Search | ||
|
||
Use `fullText` for efficient search capabilities. Text indexes are automatically created for you. Your strings are turned into tokens for fast searching. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Stylistic
|
||
|
||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would put the note regarding the 'cost' of full text search ops up here instead. That way it's a disclaimer of sorts as to what kind of impact this may have, before they start seeing any examples. |
||
Requires Parse-Server 2.5.0+ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So although Parse-Server is accurate to the project repo name we should probably be describing it as Parse Server. Unless we're referring to the repo itself the spaced name is a more appropriate way to describe it in most cases. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I've typed parse-server more than I've typed my own name |
||
|
||
<pre><code class="javascript"> | ||
var query = new Parse.Query(BarbecueSauce); | ||
query.fullText('name', 'bbq'); | ||
</code></pre> | ||
|
||
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. | ||
|
||
<pre><code class="javascript"> | ||
// You can sort by weight / rank. ascending('') and select() | ||
var query = new Parse.Query(BarbecueSauce); | ||
query.fullText('name', 'bbq'); | ||
query.ascending('$score'); | ||
query.select('$score'); | ||
query.find() | ||
.then(function(results) { | ||
// results contains a weight / rank in result.get('score') | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
|
||
|
||
For Case or Diacritic Sensitive search, please use the [REST API](http://docs.parseplatform.org/rest/guide/#queries-on-string-values). | ||
|
||
* Note: Full Text Search can be expensive operations. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. *this would be the note to move up ^, and maybe with some further clarification as to 'expensive operations'. |
||
|
||
## Relational Queries | ||
|
||
|
@@ -391,3 +424,112 @@ mainQuery.find() | |
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
## Aggregate | ||
|
||
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 | ||
|
||
* Note: MasterKey is Required. Parse-Server 2.7.1+ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Parse-Server thing |
||
|
||
Aggregates use stages to filter results by piping results from one stage to the next. | ||
|
||
You can create a pipeline using an Array or an Object. | ||
|
||
The following example is a pipeline similar to `distinct` grouping by name field. | ||
|
||
<pre><code class="javascript"> | ||
// Pipeline object | ||
const pipeline = { | ||
group: { objectId: '$name' } | ||
}; | ||
|
||
// Pipeline array | ||
const pipeline = [ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should either rename to 'pipelineArray' or change from const to var or let. In the same example you have two constants declared with the same name, and although it's just an example it should probably show correct code 😉 . |
||
{ group: { objectId: '$name' } } | ||
]; | ||
</code></pre> | ||
|
||
For a list of available operators please refer to [Mongo Aggregate Documentation](https://docs.mongodb.com/v3.2/reference/operator/aggregation/). | ||
|
||
* Note: Most operation in Mongo Aggregate Documentation will work with Parse-Server, but `_id` doesn't exist. Please replace with `objectId`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo:
|
||
|
||
<pre><code class="javascript"> | ||
// Can apply $sum, $avg, $max, $min | ||
const pipeline = [ | ||
group: { objectId: null, total: { $sum: '$score' } } | ||
]; | ||
var query = new Parse.Query("User"); | ||
query.aggregate(pipeline); | ||
query.find() | ||
.then(function(results) { | ||
// results contains sum of score field and stores it in results[0].total | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
<pre><code class="javascript"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I would add some descriptive text before this code block to detail what's in it, especially since it's only preceded by another block. |
||
// project pipeline is similar to keys / select, add or remove existing fields | ||
const pipeline = [ | ||
project: { name: 1 } | ||
]; | ||
var query = new Parse.Query("User"); | ||
query.aggregate(pipeline); | ||
query.find() | ||
.then(function(results) { | ||
// results contains only name field | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
<pre><code class="javascript"> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Same thing here, something before it to describe and break it up would be nice. |
||
// match pipeline is similar to equalTo | ||
const pipeline = [ | ||
match: { score: { $gt: 15 } } | ||
]; | ||
var query = new Parse.Query("User"); | ||
query.aggregate(pipeline); | ||
query.find() | ||
.then(function(results) { | ||
// results contains score greater than 15 | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
## Distinct | ||
|
||
Queries can be made using distinct, allowing you find unique values for a specified field. | ||
|
||
* Note: MasterKey is required. Parse-Server 2.7.1+ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Parse-Server thing |
||
|
||
<pre><code class="javascript"> | ||
var query = new Parse.Query("User"); | ||
query.distinct("age"); | ||
query.find() | ||
.then(function(results) { | ||
// results contains unique age | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> | ||
|
||
You can also restrict results by using `equalTo` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Missing a period (or colon) at the end of this sentence |
||
|
||
<pre><code class="javascript"> | ||
var query = new Parse.Query("User"); | ||
query.equalTo("name", "foo"); | ||
query.distinct("age"); | ||
query.find() | ||
.then(function(results) { | ||
// results contains unique age where name is foo | ||
}) | ||
.catch(function(error) { | ||
// There was an error. | ||
}); | ||
</code></pre> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,145 @@ | ||
# Schema | ||
|
||
Schema is the structure representing classes in your app. You can use the schema | ||
of an app to verify operations in a unit test, generate test data, generate test | ||
classes and then clean up after tests. The schema API can also be used to create | ||
custom views of your data. We use the schema API to display columns names and | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. typo on plural column:
|
||
types in the databrowser. | ||
|
||
This API allows you to access the schemas of your app. | ||
|
||
* `MasterKey` is required. | ||
* Starting with Parse-Server 2.7.1 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Parse-Server thing |
||
|
||
Schema will return an object similar to the following: | ||
|
||
<pre><code class="javascript"> | ||
{ | ||
className: 'MyClass', | ||
fields: { | ||
//Default fields | ||
ACL: {type: 'ACL'}, | ||
createdAt: {type: 'Date'}, | ||
updatedAt: {type: 'Date'}, | ||
objectId: {type: 'String'}, | ||
//Custom fields | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. could put a space here to visually separate default from custom fields, purely stylistic however. |
||
aNumber: {type: 'Number'}, | ||
aString: {type: 'String'}, | ||
aBool: {type: 'Boolean'}, | ||
aDate: {type: 'Date'}, | ||
aObject: {type: 'Object'}, | ||
aArray: {type: 'Array'}, | ||
aGeoPoint: {type: 'GeoPoint'}, | ||
aPolygon: {type: 'Polygon'}, | ||
aFile: {type: 'File'} | ||
}, | ||
classLevelPermissions: { | ||
find: { | ||
'*': true | ||
}, | ||
create: { | ||
'*': true | ||
}, | ||
get: { | ||
'*': true | ||
}, | ||
update: { | ||
'*': true | ||
}, | ||
addField: { | ||
'*': true | ||
}, | ||
delete: { | ||
'*': true | ||
} | ||
}, | ||
indexes: { | ||
indexName: { aString: 1 }, | ||
} | ||
} | ||
</code></pre> | ||
|
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Probably would be good to add a little warning with this as well.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I like |
||
|
||
<pre><code class="javascript"> | ||
// create an instance to manage your class | ||
const mySchema = new Parse.Schema('MyClass'); | ||
|
||
// gets the current schema data | ||
mySchema.get(); | ||
|
||
// returns schema for all classes | ||
Parse.Schema.all() | ||
|
||
// add any # of fields, without having to create any objects | ||
mySchema | ||
.addString('stringField') | ||
.addNumber('numberField') | ||
.addBoolean('booleanField') | ||
.addDate('dateField') | ||
.addFile('fileField') | ||
.addGeoPoint('geoPointField') | ||
.addPolygon('polygonField') | ||
.addArray('arrayField') | ||
.addObject('objectField') | ||
.addPointer('pointerField', '_User') | ||
.addRelation('relationField', '_User'); | ||
|
||
// new types can be added as they are available | ||
mySchema.addField('newField', 'ANewDataType') | ||
|
||
// save/update this schema to persist your field changes | ||
mySchema.save().then((result) => { | ||
// returns save new schema | ||
}); | ||
// or | ||
mySchema.update().then((result) => { | ||
// updates existing schema | ||
}); | ||
</code></pre> | ||
|
||
Assuming you want to remove a field you can simply call `deleteField` and `save/update` to clear it out. | ||
|
||
<pre><code class="javascript"> | ||
mySchema.deleteField('stringField'); | ||
mySchema.save(); | ||
// or for an existing schema... | ||
mySchema.update(); | ||
</code></pre> | ||
|
||
## Indexes | ||
|
||
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. | ||
|
||
<pre><code class="javascript"> | ||
// To add an index, the field must exist before you create an index | ||
mySchema.addString('stringField'); | ||
const index = { | ||
stringField: 1 | ||
}; | ||
mySchema.addIndex('stringFieldIndex', index); | ||
mySchema.save().then((result) => { | ||
// returns schema including index stringFieldIndex and field stringField | ||
}); | ||
|
||
// Delete an index | ||
testSchema.deleteIndex('indexName'); | ||
mySchema.save().then((result) => { | ||
// returns schema without indexName index | ||
}); | ||
|
||
// If indexes exist, you can retrieve them | ||
mySchema.get().then((result) => { | ||
// result.indexes | ||
}); | ||
</code></pre> | ||
|
||
## Purge | ||
|
||
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). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Could italicize be careful to stress it. |
||
|
||
<pre><code class="javascript"> | ||
// delete all objects in the schema | ||
mySchema.purge(); | ||
</code></pre> | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can probably replace the / with 'or' just to be a bit more explicit.