DOCS-1639: Recommend BSON date

[andf-viam]

Recommend that MQL query users use the built-in BSON date type instead of converting from string.

• Usage example include both usages users care about:
  • Using date type for explicit date specified as string to Date() constructor
  • Using Date() constructor without argument to use current timestamp.

Question:

• I can link to BSON spec itself if too many MDB docs links already, up to you.

[viambot]

Overall readability score: 55.6 (🟢 +0)

File	Readability
query.md	57.72 (🔴 -0.54)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
query.md	57.72	42.92	10	14.1	12.53	6.46
	🔴 -0.54	🔴 -0.3	🔴 -0.31	🟢 +0	🟢 +0.12	🔴 -0.04

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	55.6	47.52	10.65	13.22	12.08	7.61
	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[andf-viam]

Hi @dmhilly - quick clarification to recommend using the BSON date data type in MQL queries, with an example based on Jack's code as linked in the DOCS ticket. LMK if you'd like to see any changes -- thanks!

[dmhilly]

This looks great, thanks Andrew! Left a couple suggestions

[dmhilly]

I can link to BSON spec itself if too many MDB docs links already, up to you.

I think using the MongoDB documentation is okay! It has more info than the BSON spec

[dmhilly]

Suggested change

	For example, you could use the following to query a dataset over a date range, specifying a target start timestamp in BSON date format, and using the `Date()` constructor to use the current time as the end timestamp:
	For example, you could use the following to query a dataset over a date range, specifying a target start timestamp in BSON date format, and using the JavaScript `Date()` constructor to use the current time as the end timestamp:

Thoughts? Just to make it clear that this is specific to JavaScript/the shell, since to construct a date type in another language they will need to use the language-specific constructs

[andf-viam]

Right on, this is indeed continuing the mongoh example, so JS it is. Clarified this a bit, thank you!

[dmhilly]

Ah I just noticed that this is a string type, not a date. That might confuse users. I don't really know JS but maybe we want something like:

const startTime = new Date('Mon Feb 10 2024 14:45:07 GMT-0500 (Eastern Standard Time)')

[andf-viam]

Ah, you're right I think, and we can simplify it a bit too if we're using Date() then. Thanks!

[dmhilly]

The changes look great - LGTM! 🎉

[viambot]

You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/2582