Skip to content

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

Merged
merged 3 commits into from
Jan 18, 2018
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions _includes/js/geopoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Copy link
Contributor

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.


<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`:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stylistic

You can also query for whether...


<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:
Expand Down
142 changes: 142 additions & 0 deletions _includes/js/queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stylistic

You can use fullText for efficient...


Copy link
Contributor

Choose a reason for hiding this comment

The 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+
Copy link
Contributor

Choose a reason for hiding this comment

The 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.

Copy link
Member Author

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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

Expand Down Expand Up @@ -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+
Copy link
Contributor

Choose a reason for hiding this comment

The 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 = [
Copy link
Contributor

Choose a reason for hiding this comment

The 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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo:

Most operations in...


<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">
Copy link
Contributor

Choose a reason for hiding this comment

The 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">
Copy link
Contributor

Choose a reason for hiding this comment

The 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+
Copy link
Contributor

Choose a reason for hiding this comment

The 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`
Copy link
Contributor

Choose a reason for hiding this comment

The 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>
145 changes: 145 additions & 0 deletions _includes/js/schema.md
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo on plural column:

to display columns names and

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
Copy link
Contributor

Choose a reason for hiding this comment

The 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
Copy link
Contributor

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The 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.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The 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).
Copy link
Contributor

Choose a reason for hiding this comment

The 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>

Loading